Mercurial > repos > rliterman > csp2
comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/gettext/gettext_9.html @ 68:5028fdace37b
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
| author | jpayne |
|---|---|
| date | Tue, 18 Mar 2025 16:23:26 -0400 |
| parents | |
| children |
comparison
equal
deleted
inserted
replaced
| 67:0e9998148a16 | 68:5028fdace37b |
|---|---|
| 1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd"> | |
| 2 <html> | |
| 3 <!-- Created on February, 21 2024 by texi2html 1.78a --> | |
| 4 <!-- | |
| 5 Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author) | |
| 6 Karl Berry <karl@freefriends.org> | |
| 7 Olaf Bachmann <obachman@mathematik.uni-kl.de> | |
| 8 and many others. | |
| 9 Maintained by: Many creative people. | |
| 10 Send bugs and suggestions to <texi2html-bug@nongnu.org> | |
| 11 | |
| 12 --> | |
| 13 <head> | |
| 14 <title>GNU gettext utilities: 9. Manipulating PO Files</title> | |
| 15 | |
| 16 <meta name="description" content="GNU gettext utilities: 9. Manipulating PO Files"> | |
| 17 <meta name="keywords" content="GNU gettext utilities: 9. Manipulating PO Files"> | |
| 18 <meta name="resource-type" content="document"> | |
| 19 <meta name="distribution" content="global"> | |
| 20 <meta name="Generator" content="texi2html 1.78a"> | |
| 21 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> | |
| 22 <style type="text/css"> | |
| 23 <!-- | |
| 24 a.summary-letter {text-decoration: none} | |
| 25 pre.display {font-family: serif} | |
| 26 pre.format {font-family: serif} | |
| 27 pre.menu-comment {font-family: serif} | |
| 28 pre.menu-preformatted {font-family: serif} | |
| 29 pre.smalldisplay {font-family: serif; font-size: smaller} | |
| 30 pre.smallexample {font-size: smaller} | |
| 31 pre.smallformat {font-family: serif; font-size: smaller} | |
| 32 pre.smalllisp {font-size: smaller} | |
| 33 span.roman {font-family:serif; font-weight:normal;} | |
| 34 span.sansserif {font-family:sans-serif; font-weight:normal;} | |
| 35 ul.toc {list-style: none} | |
| 36 --> | |
| 37 </style> | |
| 38 | |
| 39 | |
| 40 </head> | |
| 41 | |
| 42 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> | |
| 43 | |
| 44 <table cellpadding="1" cellspacing="1" border="0"> | |
| 45 <tr><td valign="middle" align="left">[<a href="gettext_8.html#SEC63" title="Beginning of this chapter or previous chapter"> << </a>]</td> | |
| 46 <td valign="middle" align="left">[<a href="gettext_10.html#SEC173" title="Next chapter"> >> </a>]</td> | |
| 47 <td valign="middle" align="left"> </td> | |
| 48 <td valign="middle" align="left"> </td> | |
| 49 <td valign="middle" align="left"> </td> | |
| 50 <td valign="middle" align="left"> </td> | |
| 51 <td valign="middle" align="left"> </td> | |
| 52 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td> | |
| 53 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td> | |
| 54 <td valign="middle" align="left">[<a href="gettext_21.html#SEC389" title="Index">Index</a>]</td> | |
| 55 <td valign="middle" align="left">[<a href="gettext_abt.html#SEC_About" title="About (help)"> ? </a>]</td> | |
| 56 </tr></table> | |
| 57 | |
| 58 <hr size="2"> | |
| 59 <a name="Manipulating"></a> | |
| 60 <a name="SEC87"></a> | |
| 61 <h1 class="chapter"> <a href="gettext_toc.html#TOC80">9. Manipulating PO Files</a> </h1> | |
| 62 | |
| 63 <p>Sometimes it is necessary to manipulate PO files in a way that is better | |
| 64 performed automatically than by hand. GNU <code>gettext</code> includes a | |
| 65 complete set of tools for this purpose. | |
| 66 </p> | |
| 67 <a name="IDX484"></a> | |
| 68 <p>When merging two packages into a single package, the resulting POT file | |
| 69 will be the concatenation of the two packages' POT files. Thus the | |
| 70 maintainer must concatenate the two existing package translations into | |
| 71 a single translation catalog, for each language. This is best performed | |
| 72 using ‘<samp>msgcat</samp>’. It is then the translators' duty to deal with any | |
| 73 possible conflicts that arose during the merge. | |
| 74 </p> | |
| 75 <a name="IDX485"></a> | |
| 76 <p>When a translator takes over the translation job from another translator, | |
| 77 but she uses a different character encoding in her locale, she will | |
| 78 convert the catalog to her character encoding. This is best done through | |
| 79 the ‘<samp>msgconv</samp>’ program. | |
| 80 </p> | |
| 81 <p>When a maintainer takes a source file with tagged messages from another | |
| 82 package, he should also take the existing translations for this source | |
| 83 file (and not let the translators do the same job twice). One way to do | |
| 84 this is through ‘<samp>msggrep</samp>’, another is to create a POT file for | |
| 85 that source file and use ‘<samp>msgmerge</samp>’. | |
| 86 </p> | |
| 87 <a name="IDX486"></a> | |
| 88 <a name="IDX487"></a> | |
| 89 <p>When a translator wants to adjust some translation catalog for a special | |
| 90 dialect or orthography — for example, German as written in Switzerland | |
| 91 versus German as written in Germany — she needs to apply some text | |
| 92 processing to every message in the catalog. The tool for doing this is | |
| 93 ‘<samp>msgfilter</samp>’. | |
| 94 </p> | |
| 95 <p>Another use of <code>msgfilter</code> is to produce approximately the POT file for | |
| 96 which a given PO file was made. This can be done through a filter command | |
| 97 like ‘<samp>msgfilter sed -e d | sed -e '/^# /d'</samp>’. Note that the original | |
| 98 POT file may have had different comments and different plural message counts, | |
| 99 that's why it's better to use the original POT file if available. | |
| 100 </p> | |
| 101 <a name="IDX488"></a> | |
| 102 <p>When a translator wants to check her translations, for example according | |
| 103 to orthography rules or using a non-interactive spell checker, she can do | |
| 104 so using the ‘<samp>msgexec</samp>’ program. | |
| 105 </p> | |
| 106 <a name="IDX489"></a> | |
| 107 <p>When third party tools create PO or POT files, sometimes duplicates cannot | |
| 108 be avoided. But the GNU <code>gettext</code> tools give an error when they | |
| 109 encounter duplicate msgids in the same file and in the same domain. | |
| 110 To merge duplicates, the ‘<samp>msguniq</samp>’ program can be used. | |
| 111 </p> | |
| 112 <p>‘<samp>msgcomm</samp>’ is a more general tool for keeping or throwing away | |
| 113 duplicates, occurring in different files. | |
| 114 </p> | |
| 115 <p>‘<samp>msgcmp</samp>’ can be used to check whether a translation catalog is | |
| 116 completely translated. | |
| 117 </p> | |
| 118 <a name="IDX490"></a> | |
| 119 <p>‘<samp>msgattrib</samp>’ can be used to select and extract only the fuzzy | |
| 120 or untranslated messages of a translation catalog. | |
| 121 </p> | |
| 122 <p>‘<samp>msgen</samp>’ is useful as a first step for preparing English translation | |
| 123 catalogs. It copies each message's msgid to its msgstr. | |
| 124 </p> | |
| 125 <p>Finally, for those applications where all these various programs are not | |
| 126 sufficient, a library ‘<samp>libgettextpo</samp>’ is provided that can be used to | |
| 127 write other specialized programs that process PO files. | |
| 128 </p> | |
| 129 | |
| 130 | |
| 131 <a name="msgcat-Invocation"></a> | |
| 132 <a name="SEC88"></a> | |
| 133 <h2 class="section"> <a href="gettext_toc.html#TOC81">9.1 Invoking the <code>msgcat</code> Program</a> </h2> | |
| 134 | |
| 135 | |
| 136 <table><tr><td> </td><td><pre class="example">msgcat [<var>option</var>] [<var>inputfile</var>]... | |
| 137 </pre></td></tr></table> | |
| 138 | |
| 139 <a name="IDX491"></a> | |
| 140 <a name="IDX492"></a> | |
| 141 <p>The <code>msgcat</code> program concatenates and merges the specified PO files. | |
| 142 It finds messages which are common to two or more of the specified PO files. | |
| 143 By using the <code>--more-than</code> option, greater commonality may be requested | |
| 144 before messages are printed. Conversely, the <code>--less-than</code> option may be | |
| 145 used to specify less commonality before messages are printed (i.e. | |
| 146 ‘<samp>--less-than=2</samp>’ will only print the unique messages). Translations, | |
| 147 comments, extracted comments, and file positions will be cumulated, except that | |
| 148 if <code>--use-first</code> is specified, they will be taken from the first PO file | |
| 149 to define them. | |
| 150 </p> | |
| 151 <p>To concatenate POT files, better use <code>xgettext</code>, not <code>msgcat</code>, | |
| 152 because <code>msgcat</code> would choke on the undefined charsets in the specified | |
| 153 POT files. | |
| 154 </p> | |
| 155 | |
| 156 <a name="SEC89"></a> | |
| 157 <h3 class="subsection"> <a href="gettext_toc.html#TOC82">9.1.1 Input file location</a> </h3> | |
| 158 | |
| 159 <dl compact="compact"> | |
| 160 <dt> ‘<samp><var>inputfile</var> …</samp>’</dt> | |
| 161 <dd><p>Input files. | |
| 162 </p> | |
| 163 </dd> | |
| 164 <dt> ‘<samp>-f <var>file</var></samp>’</dt> | |
| 165 <dt> ‘<samp>--files-from=<var>file</var></samp>’</dt> | |
| 166 <dd><a name="IDX493"></a> | |
| 167 <a name="IDX494"></a> | |
| 168 <p>Read the names of the input files from <var>file</var> instead of getting | |
| 169 them from the command line. | |
| 170 </p> | |
| 171 </dd> | |
| 172 <dt> ‘<samp>-D <var>directory</var></samp>’</dt> | |
| 173 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt> | |
| 174 <dd><a name="IDX495"></a> | |
| 175 <a name="IDX496"></a> | |
| 176 <p>Add <var>directory</var> to the list of directories. Source files are | |
| 177 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’ | |
| 178 file will be written relative to the current directory, though. | |
| 179 </p> | |
| 180 </dd> | |
| 181 </dl> | |
| 182 | |
| 183 <p>If <var>inputfile</var> is ‘<samp>-</samp>’, standard input is read. | |
| 184 </p> | |
| 185 | |
| 186 <a name="SEC90"></a> | |
| 187 <h3 class="subsection"> <a href="gettext_toc.html#TOC83">9.1.2 Output file location</a> </h3> | |
| 188 | |
| 189 <dl compact="compact"> | |
| 190 <dt> ‘<samp>-o <var>file</var></samp>’</dt> | |
| 191 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt> | |
| 192 <dd><a name="IDX497"></a> | |
| 193 <a name="IDX498"></a> | |
| 194 <p>Write output to specified file. | |
| 195 </p> | |
| 196 </dd> | |
| 197 </dl> | |
| 198 | |
| 199 <a name="IDX499"></a> | |
| 200 <p>The results are written to standard output if no output file is specified | |
| 201 or if it is ‘<samp>-</samp>’. | |
| 202 </p> | |
| 203 | |
| 204 <a name="SEC91"></a> | |
| 205 <h3 class="subsection"> <a href="gettext_toc.html#TOC84">9.1.3 Message selection</a> </h3> | |
| 206 | |
| 207 <dl compact="compact"> | |
| 208 <dt> ‘<samp>-< <var>number</var></samp>’</dt> | |
| 209 <dt> ‘<samp>--less-than=<var>number</var></samp>’</dt> | |
| 210 <dd><a name="IDX500"></a> | |
| 211 <a name="IDX501"></a> | |
| 212 <p>Print messages with less than <var>number</var> definitions, defaults to infinite | |
| 213 if not set. | |
| 214 </p> | |
| 215 </dd> | |
| 216 <dt> ‘<samp>-> <var>number</var></samp>’</dt> | |
| 217 <dt> ‘<samp>--more-than=<var>number</var></samp>’</dt> | |
| 218 <dd><a name="IDX502"></a> | |
| 219 <a name="IDX503"></a> | |
| 220 <p>Print messages with more than <var>number</var> definitions, defaults to 0 if not | |
| 221 set. | |
| 222 </p> | |
| 223 </dd> | |
| 224 <dt> ‘<samp>-u</samp>’</dt> | |
| 225 <dt> ‘<samp>--unique</samp>’</dt> | |
| 226 <dd><a name="IDX504"></a> | |
| 227 <a name="IDX505"></a> | |
| 228 <p>Shorthand for ‘<samp>--less-than=2</samp>’. Requests that only unique messages be | |
| 229 printed. | |
| 230 </p> | |
| 231 </dd> | |
| 232 </dl> | |
| 233 | |
| 234 | |
| 235 <a name="SEC92"></a> | |
| 236 <h3 class="subsection"> <a href="gettext_toc.html#TOC85">9.1.4 Input file syntax</a> </h3> | |
| 237 | |
| 238 <dl compact="compact"> | |
| 239 <dt> ‘<samp>-P</samp>’</dt> | |
| 240 <dt> ‘<samp>--properties-input</samp>’</dt> | |
| 241 <dd><a name="IDX506"></a> | |
| 242 <a name="IDX507"></a> | |
| 243 <p>Assume the input files are Java ResourceBundles in Java <code>.properties</code> | |
| 244 syntax, not in PO file syntax. | |
| 245 </p> | |
| 246 </dd> | |
| 247 <dt> ‘<samp>--stringtable-input</samp>’</dt> | |
| 248 <dd><a name="IDX508"></a> | |
| 249 <p>Assume the input files are NeXTstep/GNUstep localized resource files in | |
| 250 <code>.strings</code> syntax, not in PO file syntax. | |
| 251 </p> | |
| 252 </dd> | |
| 253 </dl> | |
| 254 | |
| 255 | |
| 256 <a name="SEC93"></a> | |
| 257 <h3 class="subsection"> <a href="gettext_toc.html#TOC86">9.1.5 Output details</a> </h3> | |
| 258 | |
| 259 | |
| 260 <dl compact="compact"> | |
| 261 <dt> ‘<samp>-t</samp>’</dt> | |
| 262 <dt> ‘<samp>--to-code=<var>name</var></samp>’</dt> | |
| 263 <dd><a name="IDX509"></a> | |
| 264 <a name="IDX510"></a> | |
| 265 <p>Specify encoding for output. | |
| 266 </p> | |
| 267 </dd> | |
| 268 <dt> ‘<samp>--use-first</samp>’</dt> | |
| 269 <dd><a name="IDX511"></a> | |
| 270 <p>Use first available translation for each message. Don't merge several | |
| 271 translations into one. | |
| 272 </p> | |
| 273 </dd> | |
| 274 <dt> ‘<samp>--lang=<var>catalogname</var></samp>’</dt> | |
| 275 <dd><a name="IDX512"></a> | |
| 276 <p>Specify the ‘<samp>Language</samp>’ field to be used in the header entry. See | |
| 277 <a href="gettext_6.html#SEC52">Filling in the Header Entry</a> for the meaning of this field. Note: The | |
| 278 ‘<samp>Language-Team</samp>’ and ‘<samp>Plural-Forms</samp>’ fields are left unchanged. | |
| 279 </p> | |
| 280 </dd> | |
| 281 <dt> ‘<samp>--color</samp>’</dt> | |
| 282 <dt> ‘<samp>--color=<var>when</var></samp>’</dt> | |
| 283 <dd><a name="IDX513"></a> | |
| 284 <p>Specify whether or when to use colors and other text attributes. | |
| 285 See <a href="#SEC158">The <code>--color</code> option</a> for details. | |
| 286 </p> | |
| 287 </dd> | |
| 288 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt> | |
| 289 <dd><a name="IDX514"></a> | |
| 290 <p>Specify the CSS style rule file to use for <code>--color</code>. | |
| 291 See <a href="#SEC160">The <code>--style</code> option</a> for details. | |
| 292 </p> | |
| 293 </dd> | |
| 294 <dt> ‘<samp>--force-po</samp>’</dt> | |
| 295 <dd><a name="IDX515"></a> | |
| 296 <p>Always write an output file even if it contains no message. | |
| 297 </p> | |
| 298 </dd> | |
| 299 <dt> ‘<samp>-i</samp>’</dt> | |
| 300 <dt> ‘<samp>--indent</samp>’</dt> | |
| 301 <dd><a name="IDX516"></a> | |
| 302 <a name="IDX517"></a> | |
| 303 <p>Write the .po file using indented style. | |
| 304 </p> | |
| 305 </dd> | |
| 306 <dt> ‘<samp>--no-location</samp>’</dt> | |
| 307 <dd><a name="IDX518"></a> | |
| 308 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines. | |
| 309 </p> | |
| 310 </dd> | |
| 311 <dt> ‘<samp>-n</samp>’</dt> | |
| 312 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt> | |
| 313 <dd><a name="IDX519"></a> | |
| 314 <a name="IDX520"></a> | |
| 315 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default). | |
| 316 </p> | |
| 317 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or | |
| 318 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the | |
| 319 lines with both file name and line number. If it is ‘<samp>file</samp>’, the | |
| 320 line number part is omitted. If it is ‘<samp>never</samp>’, it completely | |
| 321 suppresses the lines (same as <code>--no-location</code>). | |
| 322 </p> | |
| 323 </dd> | |
| 324 <dt> ‘<samp>--strict</samp>’</dt> | |
| 325 <dd><a name="IDX521"></a> | |
| 326 <p>Write out a strict Uniforum conforming PO file. Note that this | |
| 327 Uniforum format should be avoided because it doesn't support the | |
| 328 GNU extensions. | |
| 329 </p> | |
| 330 </dd> | |
| 331 <dt> ‘<samp>-p</samp>’</dt> | |
| 332 <dt> ‘<samp>--properties-output</samp>’</dt> | |
| 333 <dd><a name="IDX522"></a> | |
| 334 <a name="IDX523"></a> | |
| 335 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note | |
| 336 that this file format doesn't support plural forms and silently drops | |
| 337 obsolete messages. | |
| 338 </p> | |
| 339 </dd> | |
| 340 <dt> ‘<samp>--stringtable-output</samp>’</dt> | |
| 341 <dd><a name="IDX524"></a> | |
| 342 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. | |
| 343 Note that this file format doesn't support plural forms. | |
| 344 </p> | |
| 345 </dd> | |
| 346 <dt> ‘<samp>-w <var>number</var></samp>’</dt> | |
| 347 <dt> ‘<samp>--width=<var>number</var></samp>’</dt> | |
| 348 <dd><a name="IDX525"></a> | |
| 349 <a name="IDX526"></a> | |
| 350 <p>Set the output page width. Long strings in the output files will be | |
| 351 split across multiple lines in order to ensure that each line's width | |
| 352 (= number of screen columns) is less or equal to the given <var>number</var>. | |
| 353 </p> | |
| 354 </dd> | |
| 355 <dt> ‘<samp>--no-wrap</samp>’</dt> | |
| 356 <dd><a name="IDX527"></a> | |
| 357 <p>Do not break long message lines. Message lines whose width exceeds the | |
| 358 output page width will not be split into several lines. Only file reference | |
| 359 lines which are wider than the output page width will be split. | |
| 360 </p> | |
| 361 </dd> | |
| 362 <dt> ‘<samp>-s</samp>’</dt> | |
| 363 <dt> ‘<samp>--sort-output</samp>’</dt> | |
| 364 <dd><a name="IDX528"></a> | |
| 365 <a name="IDX529"></a> | |
| 366 <a name="IDX530"></a> | |
| 367 <p>Generate sorted output. Note that using this option makes it much harder | |
| 368 for the translator to understand each message's context. | |
| 369 </p> | |
| 370 </dd> | |
| 371 <dt> ‘<samp>-F</samp>’</dt> | |
| 372 <dt> ‘<samp>--sort-by-file</samp>’</dt> | |
| 373 <dd><a name="IDX531"></a> | |
| 374 <a name="IDX532"></a> | |
| 375 <p>Sort output by file location. | |
| 376 </p> | |
| 377 </dd> | |
| 378 </dl> | |
| 379 | |
| 380 | |
| 381 <a name="SEC94"></a> | |
| 382 <h3 class="subsection"> <a href="gettext_toc.html#TOC87">9.1.6 Informative output</a> </h3> | |
| 383 | |
| 384 <dl compact="compact"> | |
| 385 <dt> ‘<samp>-h</samp>’</dt> | |
| 386 <dt> ‘<samp>--help</samp>’</dt> | |
| 387 <dd><a name="IDX533"></a> | |
| 388 <a name="IDX534"></a> | |
| 389 <p>Display this help and exit. | |
| 390 </p> | |
| 391 </dd> | |
| 392 <dt> ‘<samp>-V</samp>’</dt> | |
| 393 <dt> ‘<samp>--version</samp>’</dt> | |
| 394 <dd><a name="IDX535"></a> | |
| 395 <a name="IDX536"></a> | |
| 396 <p>Output version information and exit. | |
| 397 </p> | |
| 398 </dd> | |
| 399 </dl> | |
| 400 | |
| 401 | |
| 402 <a name="msgconv-Invocation"></a> | |
| 403 <a name="SEC95"></a> | |
| 404 <h2 class="section"> <a href="gettext_toc.html#TOC88">9.2 Invoking the <code>msgconv</code> Program</a> </h2> | |
| 405 | |
| 406 | |
| 407 <table><tr><td> </td><td><pre class="example">msgconv [<var>option</var>] [<var>inputfile</var>] | |
| 408 </pre></td></tr></table> | |
| 409 | |
| 410 <a name="IDX537"></a> | |
| 411 <p>The <code>msgconv</code> program converts a translation catalog to a different | |
| 412 character encoding. | |
| 413 </p> | |
| 414 | |
| 415 <a name="SEC96"></a> | |
| 416 <h3 class="subsection"> <a href="gettext_toc.html#TOC89">9.2.1 Input file location</a> </h3> | |
| 417 | |
| 418 <dl compact="compact"> | |
| 419 <dt> ‘<samp><var>inputfile</var></samp>’</dt> | |
| 420 <dd><p>Input PO file. | |
| 421 </p> | |
| 422 </dd> | |
| 423 <dt> ‘<samp>-D <var>directory</var></samp>’</dt> | |
| 424 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt> | |
| 425 <dd><a name="IDX538"></a> | |
| 426 <a name="IDX539"></a> | |
| 427 <p>Add <var>directory</var> to the list of directories. Source files are | |
| 428 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’ | |
| 429 file will be written relative to the current directory, though. | |
| 430 </p> | |
| 431 </dd> | |
| 432 </dl> | |
| 433 | |
| 434 <p>If no <var>inputfile</var> is given or if it is ‘<samp>-</samp>’, standard input is read. | |
| 435 </p> | |
| 436 | |
| 437 <a name="SEC97"></a> | |
| 438 <h3 class="subsection"> <a href="gettext_toc.html#TOC90">9.2.2 Output file location</a> </h3> | |
| 439 | |
| 440 <dl compact="compact"> | |
| 441 <dt> ‘<samp>-o <var>file</var></samp>’</dt> | |
| 442 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt> | |
| 443 <dd><a name="IDX540"></a> | |
| 444 <a name="IDX541"></a> | |
| 445 <p>Write output to specified file. | |
| 446 </p> | |
| 447 </dd> | |
| 448 </dl> | |
| 449 | |
| 450 <p>The results are written to standard output if no output file is specified | |
| 451 or if it is ‘<samp>-</samp>’. | |
| 452 </p> | |
| 453 | |
| 454 <a name="SEC98"></a> | |
| 455 <h3 class="subsection"> <a href="gettext_toc.html#TOC91">9.2.3 Conversion target</a> </h3> | |
| 456 | |
| 457 <dl compact="compact"> | |
| 458 <dt> ‘<samp>-t</samp>’</dt> | |
| 459 <dt> ‘<samp>--to-code=<var>name</var></samp>’</dt> | |
| 460 <dd><a name="IDX542"></a> | |
| 461 <a name="IDX543"></a> | |
| 462 <p>Specify encoding for output. | |
| 463 </p> | |
| 464 </dd> | |
| 465 </dl> | |
| 466 | |
| 467 <p>The default encoding is the current locale's encoding. | |
| 468 </p> | |
| 469 | |
| 470 <a name="SEC99"></a> | |
| 471 <h3 class="subsection"> <a href="gettext_toc.html#TOC92">9.2.4 Input file syntax</a> </h3> | |
| 472 | |
| 473 <dl compact="compact"> | |
| 474 <dt> ‘<samp>-P</samp>’</dt> | |
| 475 <dt> ‘<samp>--properties-input</samp>’</dt> | |
| 476 <dd><a name="IDX544"></a> | |
| 477 <a name="IDX545"></a> | |
| 478 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> | |
| 479 syntax, not in PO file syntax. | |
| 480 </p> | |
| 481 </dd> | |
| 482 <dt> ‘<samp>--stringtable-input</samp>’</dt> | |
| 483 <dd><a name="IDX546"></a> | |
| 484 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in | |
| 485 <code>.strings</code> syntax, not in PO file syntax. | |
| 486 </p> | |
| 487 </dd> | |
| 488 </dl> | |
| 489 | |
| 490 | |
| 491 <a name="SEC100"></a> | |
| 492 <h3 class="subsection"> <a href="gettext_toc.html#TOC93">9.2.5 Output details</a> </h3> | |
| 493 | |
| 494 | |
| 495 <dl compact="compact"> | |
| 496 <dt> ‘<samp>--color</samp>’</dt> | |
| 497 <dt> ‘<samp>--color=<var>when</var></samp>’</dt> | |
| 498 <dd><a name="IDX547"></a> | |
| 499 <p>Specify whether or when to use colors and other text attributes. | |
| 500 See <a href="#SEC158">The <code>--color</code> option</a> for details. | |
| 501 </p> | |
| 502 </dd> | |
| 503 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt> | |
| 504 <dd><a name="IDX548"></a> | |
| 505 <p>Specify the CSS style rule file to use for <code>--color</code>. | |
| 506 See <a href="#SEC160">The <code>--style</code> option</a> for details. | |
| 507 </p> | |
| 508 </dd> | |
| 509 <dt> ‘<samp>--force-po</samp>’</dt> | |
| 510 <dd><a name="IDX549"></a> | |
| 511 <p>Always write an output file even if it contains no message. | |
| 512 </p> | |
| 513 </dd> | |
| 514 <dt> ‘<samp>-i</samp>’</dt> | |
| 515 <dt> ‘<samp>--indent</samp>’</dt> | |
| 516 <dd><a name="IDX550"></a> | |
| 517 <a name="IDX551"></a> | |
| 518 <p>Write the .po file using indented style. | |
| 519 </p> | |
| 520 </dd> | |
| 521 <dt> ‘<samp>--no-location</samp>’</dt> | |
| 522 <dd><a name="IDX552"></a> | |
| 523 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines. | |
| 524 </p> | |
| 525 </dd> | |
| 526 <dt> ‘<samp>-n</samp>’</dt> | |
| 527 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt> | |
| 528 <dd><a name="IDX553"></a> | |
| 529 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default). | |
| 530 </p> | |
| 531 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or | |
| 532 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the | |
| 533 lines with both file name and line number. If it is ‘<samp>file</samp>’, the | |
| 534 line number part is omitted. If it is ‘<samp>never</samp>’, it completely | |
| 535 suppresses the lines (same as <code>--no-location</code>). | |
| 536 </p> | |
| 537 </dd> | |
| 538 <dt> ‘<samp>--strict</samp>’</dt> | |
| 539 <dd><a name="IDX554"></a> | |
| 540 <p>Write out a strict Uniforum conforming PO file. Note that this | |
| 541 Uniforum format should be avoided because it doesn't support the | |
| 542 GNU extensions. | |
| 543 </p> | |
| 544 </dd> | |
| 545 <dt> ‘<samp>-p</samp>’</dt> | |
| 546 <dt> ‘<samp>--properties-output</samp>’</dt> | |
| 547 <dd><a name="IDX555"></a> | |
| 548 <a name="IDX556"></a> | |
| 549 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note | |
| 550 that this file format doesn't support plural forms and silently drops | |
| 551 obsolete messages. | |
| 552 </p> | |
| 553 </dd> | |
| 554 <dt> ‘<samp>--stringtable-output</samp>’</dt> | |
| 555 <dd><a name="IDX557"></a> | |
| 556 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. | |
| 557 Note that this file format doesn't support plural forms. | |
| 558 </p> | |
| 559 </dd> | |
| 560 <dt> ‘<samp>-w <var>number</var></samp>’</dt> | |
| 561 <dt> ‘<samp>--width=<var>number</var></samp>’</dt> | |
| 562 <dd><a name="IDX558"></a> | |
| 563 <a name="IDX559"></a> | |
| 564 <p>Set the output page width. Long strings in the output files will be | |
| 565 split across multiple lines in order to ensure that each line's width | |
| 566 (= number of screen columns) is less or equal to the given <var>number</var>. | |
| 567 </p> | |
| 568 </dd> | |
| 569 <dt> ‘<samp>--no-wrap</samp>’</dt> | |
| 570 <dd><a name="IDX560"></a> | |
| 571 <p>Do not break long message lines. Message lines whose width exceeds the | |
| 572 output page width will not be split into several lines. Only file reference | |
| 573 lines which are wider than the output page width will be split. | |
| 574 </p> | |
| 575 </dd> | |
| 576 <dt> ‘<samp>-s</samp>’</dt> | |
| 577 <dt> ‘<samp>--sort-output</samp>’</dt> | |
| 578 <dd><a name="IDX561"></a> | |
| 579 <a name="IDX562"></a> | |
| 580 <p>Generate sorted output. Note that using this option makes it much harder | |
| 581 for the translator to understand each message's context. | |
| 582 </p> | |
| 583 </dd> | |
| 584 <dt> ‘<samp>-F</samp>’</dt> | |
| 585 <dt> ‘<samp>--sort-by-file</samp>’</dt> | |
| 586 <dd><a name="IDX563"></a> | |
| 587 <a name="IDX564"></a> | |
| 588 <p>Sort output by file location. | |
| 589 </p> | |
| 590 </dd> | |
| 591 </dl> | |
| 592 | |
| 593 | |
| 594 <a name="SEC101"></a> | |
| 595 <h3 class="subsection"> <a href="gettext_toc.html#TOC94">9.2.6 Informative output</a> </h3> | |
| 596 | |
| 597 <dl compact="compact"> | |
| 598 <dt> ‘<samp>-h</samp>’</dt> | |
| 599 <dt> ‘<samp>--help</samp>’</dt> | |
| 600 <dd><a name="IDX565"></a> | |
| 601 <a name="IDX566"></a> | |
| 602 <p>Display this help and exit. | |
| 603 </p> | |
| 604 </dd> | |
| 605 <dt> ‘<samp>-V</samp>’</dt> | |
| 606 <dt> ‘<samp>--version</samp>’</dt> | |
| 607 <dd><a name="IDX567"></a> | |
| 608 <a name="IDX568"></a> | |
| 609 <p>Output version information and exit. | |
| 610 </p> | |
| 611 </dd> | |
| 612 </dl> | |
| 613 | |
| 614 | |
| 615 <a name="msggrep-Invocation"></a> | |
| 616 <a name="SEC102"></a> | |
| 617 <h2 class="section"> <a href="gettext_toc.html#TOC95">9.3 Invoking the <code>msggrep</code> Program</a> </h2> | |
| 618 | |
| 619 | |
| 620 <table><tr><td> </td><td><pre class="example">msggrep [<var>option</var>] [<var>inputfile</var>] | |
| 621 </pre></td></tr></table> | |
| 622 | |
| 623 <a name="IDX569"></a> | |
| 624 <p>The <code>msggrep</code> program extracts all messages of a translation catalog | |
| 625 that match a given pattern or belong to some given source files. | |
| 626 </p> | |
| 627 | |
| 628 <a name="SEC103"></a> | |
| 629 <h3 class="subsection"> <a href="gettext_toc.html#TOC96">9.3.1 Input file location</a> </h3> | |
| 630 | |
| 631 <dl compact="compact"> | |
| 632 <dt> ‘<samp><var>inputfile</var></samp>’</dt> | |
| 633 <dd><p>Input PO file. | |
| 634 </p> | |
| 635 </dd> | |
| 636 <dt> ‘<samp>-D <var>directory</var></samp>’</dt> | |
| 637 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt> | |
| 638 <dd><a name="IDX570"></a> | |
| 639 <a name="IDX571"></a> | |
| 640 <p>Add <var>directory</var> to the list of directories. Source files are | |
| 641 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’ | |
| 642 file will be written relative to the current directory, though. | |
| 643 </p> | |
| 644 </dd> | |
| 645 </dl> | |
| 646 | |
| 647 <p>If no <var>inputfile</var> is given or if it is ‘<samp>-</samp>’, standard input is read. | |
| 648 </p> | |
| 649 | |
| 650 <a name="SEC104"></a> | |
| 651 <h3 class="subsection"> <a href="gettext_toc.html#TOC97">9.3.2 Output file location</a> </h3> | |
| 652 | |
| 653 <dl compact="compact"> | |
| 654 <dt> ‘<samp>-o <var>file</var></samp>’</dt> | |
| 655 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt> | |
| 656 <dd><a name="IDX572"></a> | |
| 657 <a name="IDX573"></a> | |
| 658 <p>Write output to specified file. | |
| 659 </p> | |
| 660 </dd> | |
| 661 </dl> | |
| 662 | |
| 663 <p>The results are written to standard output if no output file is specified | |
| 664 or if it is ‘<samp>-</samp>’. | |
| 665 </p> | |
| 666 | |
| 667 <a name="SEC105"></a> | |
| 668 <h3 class="subsection"> <a href="gettext_toc.html#TOC98">9.3.3 Message selection</a> </h3> | |
| 669 | |
| 670 <table><tr><td> </td><td><pre class="example"> [-N <var>sourcefile</var>]... [-M <var>domainname</var>]... | |
| 671 [-J <var>msgctxt-pattern</var>] [-K <var>msgid-pattern</var>] [-T <var>msgstr-pattern</var>] | |
| 672 [-C <var>comment-pattern</var>] | |
| 673 </pre></td></tr></table> | |
| 674 | |
| 675 <p>A message is selected if | |
| 676 </p><ul> | |
| 677 <li> it comes from one of the specified source files, | |
| 678 </li><li> or if it comes from one of the specified domains, | |
| 679 </li><li> or if ‘<samp>-J</samp>’ is given and its context (msgctxt) matches | |
| 680 <var>msgctxt-pattern</var>, | |
| 681 </li><li> or if ‘<samp>-K</samp>’ is given and its key (msgid or msgid_plural) matches | |
| 682 <var>msgid-pattern</var>, | |
| 683 </li><li> or if ‘<samp>-T</samp>’ is given and its translation (msgstr) matches | |
| 684 <var>msgstr-pattern</var>, | |
| 685 </li><li> or if ‘<samp>-C</samp>’ is given and the translator's comment matches | |
| 686 <var>comment-pattern</var>. | |
| 687 </li></ul> | |
| 688 | |
| 689 <p>When more than one selection criterion is specified, the set of selected | |
| 690 messages is the union of the selected messages of each criterion. | |
| 691 </p> | |
| 692 <p><var>msgctxt-pattern</var> or <var>msgid-pattern</var> or <var>msgstr-pattern</var> syntax: | |
| 693 </p><table><tr><td> </td><td><pre class="example"> [-E | -F] [-e <var>pattern</var> | -f <var>file</var>]... | |
| 694 </pre></td></tr></table> | |
| 695 <p><var>pattern</var>s are basic regular expressions by default, or extended regular | |
| 696 expressions if -E is given, or fixed strings if -F is given. | |
| 697 </p> | |
| 698 <dl compact="compact"> | |
| 699 <dt> ‘<samp>-N <var>sourcefile</var></samp>’</dt> | |
| 700 <dt> ‘<samp>--location=<var>sourcefile</var></samp>’</dt> | |
| 701 <dd><a name="IDX574"></a> | |
| 702 <a name="IDX575"></a> | |
| 703 <p>Select messages extracted from <var>sourcefile</var>. <var>sourcefile</var> can be | |
| 704 either a literal file name or a wildcard pattern. | |
| 705 </p> | |
| 706 </dd> | |
| 707 <dt> ‘<samp>-M <var>domainname</var></samp>’</dt> | |
| 708 <dt> ‘<samp>--domain=<var>domainname</var></samp>’</dt> | |
| 709 <dd><a name="IDX576"></a> | |
| 710 <a name="IDX577"></a> | |
| 711 <p>Select messages belonging to domain <var>domainname</var>. | |
| 712 </p> | |
| 713 </dd> | |
| 714 <dt> ‘<samp>-J</samp>’</dt> | |
| 715 <dt> ‘<samp>--msgctxt</samp>’</dt> | |
| 716 <dd><a name="IDX578"></a> | |
| 717 <a name="IDX579"></a> | |
| 718 <p>Start of patterns for the msgctxt. | |
| 719 </p> | |
| 720 </dd> | |
| 721 <dt> ‘<samp>-K</samp>’</dt> | |
| 722 <dt> ‘<samp>--msgid</samp>’</dt> | |
| 723 <dd><a name="IDX580"></a> | |
| 724 <a name="IDX581"></a> | |
| 725 <p>Start of patterns for the msgid. | |
| 726 </p> | |
| 727 </dd> | |
| 728 <dt> ‘<samp>-T</samp>’</dt> | |
| 729 <dt> ‘<samp>--msgstr</samp>’</dt> | |
| 730 <dd><a name="IDX582"></a> | |
| 731 <a name="IDX583"></a> | |
| 732 <p>Start of patterns for the msgstr. | |
| 733 </p> | |
| 734 </dd> | |
| 735 <dt> ‘<samp>-C</samp>’</dt> | |
| 736 <dt> ‘<samp>--comment</samp>’</dt> | |
| 737 <dd><a name="IDX584"></a> | |
| 738 <a name="IDX585"></a> | |
| 739 <p>Start of patterns for the translator's comment. | |
| 740 </p> | |
| 741 </dd> | |
| 742 <dt> ‘<samp>-X</samp>’</dt> | |
| 743 <dt> ‘<samp>--extracted-comment</samp>’</dt> | |
| 744 <dd><a name="IDX586"></a> | |
| 745 <a name="IDX587"></a> | |
| 746 <p>Start of patterns for the extracted comments. | |
| 747 </p> | |
| 748 </dd> | |
| 749 <dt> ‘<samp>-E</samp>’</dt> | |
| 750 <dt> ‘<samp>--extended-regexp</samp>’</dt> | |
| 751 <dd><a name="IDX588"></a> | |
| 752 <a name="IDX589"></a> | |
| 753 <p>Specify that <var>pattern</var> is an extended regular expression. | |
| 754 </p> | |
| 755 </dd> | |
| 756 <dt> ‘<samp>-F</samp>’</dt> | |
| 757 <dt> ‘<samp>--fixed-strings</samp>’</dt> | |
| 758 <dd><a name="IDX590"></a> | |
| 759 <a name="IDX591"></a> | |
| 760 <p>Specify that <var>pattern</var> is a set of newline-separated strings. | |
| 761 </p> | |
| 762 </dd> | |
| 763 <dt> ‘<samp>-e <var>pattern</var></samp>’</dt> | |
| 764 <dt> ‘<samp>--regexp=<var>pattern</var></samp>’</dt> | |
| 765 <dd><a name="IDX592"></a> | |
| 766 <a name="IDX593"></a> | |
| 767 <p>Use <var>pattern</var> as a regular expression. | |
| 768 </p> | |
| 769 </dd> | |
| 770 <dt> ‘<samp>-f <var>file</var></samp>’</dt> | |
| 771 <dt> ‘<samp>--file=<var>file</var></samp>’</dt> | |
| 772 <dd><a name="IDX594"></a> | |
| 773 <a name="IDX595"></a> | |
| 774 <p>Obtain <var>pattern</var> from <var>file</var>. | |
| 775 </p> | |
| 776 </dd> | |
| 777 <dt> ‘<samp>-i</samp>’</dt> | |
| 778 <dt> ‘<samp>--ignore-case</samp>’</dt> | |
| 779 <dd><a name="IDX596"></a> | |
| 780 <a name="IDX597"></a> | |
| 781 <p>Ignore case distinctions. | |
| 782 </p> | |
| 783 </dd> | |
| 784 <dt> ‘<samp>-v</samp>’</dt> | |
| 785 <dt> ‘<samp>--invert-match</samp>’</dt> | |
| 786 <dd><a name="IDX598"></a> | |
| 787 <a name="IDX599"></a> | |
| 788 <p>Output only the messages that do not match any selection criterion, instead | |
| 789 of the messages that match a selection criterion. | |
| 790 </p> | |
| 791 </dd> | |
| 792 </dl> | |
| 793 | |
| 794 | |
| 795 <a name="SEC106"></a> | |
| 796 <h3 class="subsection"> <a href="gettext_toc.html#TOC99">9.3.4 Input file syntax</a> </h3> | |
| 797 | |
| 798 <dl compact="compact"> | |
| 799 <dt> ‘<samp>-P</samp>’</dt> | |
| 800 <dt> ‘<samp>--properties-input</samp>’</dt> | |
| 801 <dd><a name="IDX600"></a> | |
| 802 <a name="IDX601"></a> | |
| 803 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> | |
| 804 syntax, not in PO file syntax. | |
| 805 </p> | |
| 806 </dd> | |
| 807 <dt> ‘<samp>--stringtable-input</samp>’</dt> | |
| 808 <dd><a name="IDX602"></a> | |
| 809 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in | |
| 810 <code>.strings</code> syntax, not in PO file syntax. | |
| 811 </p> | |
| 812 </dd> | |
| 813 </dl> | |
| 814 | |
| 815 | |
| 816 <a name="SEC107"></a> | |
| 817 <h3 class="subsection"> <a href="gettext_toc.html#TOC100">9.3.5 Output details</a> </h3> | |
| 818 | |
| 819 | |
| 820 <dl compact="compact"> | |
| 821 <dt> ‘<samp>--color</samp>’</dt> | |
| 822 <dt> ‘<samp>--color=<var>when</var></samp>’</dt> | |
| 823 <dd><a name="IDX603"></a> | |
| 824 <p>Specify whether or when to use colors and other text attributes. | |
| 825 See <a href="#SEC158">The <code>--color</code> option</a> for details. | |
| 826 </p> | |
| 827 </dd> | |
| 828 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt> | |
| 829 <dd><a name="IDX604"></a> | |
| 830 <p>Specify the CSS style rule file to use for <code>--color</code>. | |
| 831 See <a href="#SEC160">The <code>--style</code> option</a> for details. | |
| 832 </p> | |
| 833 </dd> | |
| 834 <dt> ‘<samp>--force-po</samp>’</dt> | |
| 835 <dd><a name="IDX605"></a> | |
| 836 <p>Always write an output file even if it contains no message. | |
| 837 </p> | |
| 838 </dd> | |
| 839 <dt> ‘<samp>--indent</samp>’</dt> | |
| 840 <dd><a name="IDX606"></a> | |
| 841 <p>Write the .po file using indented style. | |
| 842 </p> | |
| 843 </dd> | |
| 844 <dt> ‘<samp>--no-location</samp>’</dt> | |
| 845 <dd><a name="IDX607"></a> | |
| 846 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines. | |
| 847 </p> | |
| 848 </dd> | |
| 849 <dt> ‘<samp>-n</samp>’</dt> | |
| 850 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt> | |
| 851 <dd><a name="IDX608"></a> | |
| 852 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default). | |
| 853 </p> | |
| 854 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or | |
| 855 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the | |
| 856 lines with both file name and line number. If it is ‘<samp>file</samp>’, the | |
| 857 line number part is omitted. If it is ‘<samp>never</samp>’, it completely | |
| 858 suppresses the lines (same as <code>--no-location</code>). | |
| 859 </p> | |
| 860 </dd> | |
| 861 <dt> ‘<samp>--strict</samp>’</dt> | |
| 862 <dd><a name="IDX609"></a> | |
| 863 <p>Write out a strict Uniforum conforming PO file. Note that this | |
| 864 Uniforum format should be avoided because it doesn't support the | |
| 865 GNU extensions. | |
| 866 </p> | |
| 867 </dd> | |
| 868 <dt> ‘<samp>-p</samp>’</dt> | |
| 869 <dt> ‘<samp>--properties-output</samp>’</dt> | |
| 870 <dd><a name="IDX610"></a> | |
| 871 <a name="IDX611"></a> | |
| 872 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note | |
| 873 that this file format doesn't support plural forms and silently drops | |
| 874 obsolete messages. | |
| 875 </p> | |
| 876 </dd> | |
| 877 <dt> ‘<samp>--stringtable-output</samp>’</dt> | |
| 878 <dd><a name="IDX612"></a> | |
| 879 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. | |
| 880 Note that this file format doesn't support plural forms. | |
| 881 </p> | |
| 882 </dd> | |
| 883 <dt> ‘<samp>-w <var>number</var></samp>’</dt> | |
| 884 <dt> ‘<samp>--width=<var>number</var></samp>’</dt> | |
| 885 <dd><a name="IDX613"></a> | |
| 886 <a name="IDX614"></a> | |
| 887 <p>Set the output page width. Long strings in the output files will be | |
| 888 split across multiple lines in order to ensure that each line's width | |
| 889 (= number of screen columns) is less or equal to the given <var>number</var>. | |
| 890 </p> | |
| 891 </dd> | |
| 892 <dt> ‘<samp>--no-wrap</samp>’</dt> | |
| 893 <dd><a name="IDX615"></a> | |
| 894 <p>Do not break long message lines. Message lines whose width exceeds the | |
| 895 output page width will not be split into several lines. Only file reference | |
| 896 lines which are wider than the output page width will be split. | |
| 897 </p> | |
| 898 </dd> | |
| 899 <dt> ‘<samp>--sort-output</samp>’</dt> | |
| 900 <dd><a name="IDX616"></a> | |
| 901 <p>Generate sorted output. Note that using this option makes it much harder | |
| 902 for the translator to understand each message's context. | |
| 903 </p> | |
| 904 </dd> | |
| 905 <dt> ‘<samp>--sort-by-file</samp>’</dt> | |
| 906 <dd><a name="IDX617"></a> | |
| 907 <p>Sort output by file location. | |
| 908 </p> | |
| 909 </dd> | |
| 910 </dl> | |
| 911 | |
| 912 | |
| 913 <a name="SEC108"></a> | |
| 914 <h3 class="subsection"> <a href="gettext_toc.html#TOC101">9.3.6 Informative output</a> </h3> | |
| 915 | |
| 916 <dl compact="compact"> | |
| 917 <dt> ‘<samp>-h</samp>’</dt> | |
| 918 <dt> ‘<samp>--help</samp>’</dt> | |
| 919 <dd><a name="IDX618"></a> | |
| 920 <a name="IDX619"></a> | |
| 921 <p>Display this help and exit. | |
| 922 </p> | |
| 923 </dd> | |
| 924 <dt> ‘<samp>-V</samp>’</dt> | |
| 925 <dt> ‘<samp>--version</samp>’</dt> | |
| 926 <dd><a name="IDX620"></a> | |
| 927 <a name="IDX621"></a> | |
| 928 <p>Output version information and exit. | |
| 929 </p> | |
| 930 </dd> | |
| 931 </dl> | |
| 932 | |
| 933 | |
| 934 <a name="SEC109"></a> | |
| 935 <h3 class="subsection"> <a href="gettext_toc.html#TOC102">9.3.7 Examples</a> </h3> | |
| 936 | |
| 937 <p>To extract the messages that come from the source files | |
| 938 <code>gnulib-lib/error.c</code> and <code>gnulib-lib/getopt.c</code>: | |
| 939 </p> | |
| 940 <table><tr><td> </td><td><pre class="smallexample">msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po | |
| 941 </pre></td></tr></table> | |
| 942 | |
| 943 <p>To extract the messages that contain the string “Please specify” in the | |
| 944 original string: | |
| 945 </p> | |
| 946 <table><tr><td> </td><td><pre class="smallexample">msggrep --msgid -F -e 'Please specify' input.po | |
| 947 </pre></td></tr></table> | |
| 948 | |
| 949 <p>To extract the messages that have a context specifier of either “Menu>File” | |
| 950 or “Menu>Edit” or a submenu of them: | |
| 951 </p> | |
| 952 <table><tr><td> </td><td><pre class="smallexample">msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po | |
| 953 </pre></td></tr></table> | |
| 954 | |
| 955 <p>To extract the messages whose translation contains one of the strings in the | |
| 956 file <code>wordlist.txt</code>: | |
| 957 </p> | |
| 958 <table><tr><td> </td><td><pre class="smallexample">msggrep --msgstr -F -f wordlist.txt input.po | |
| 959 </pre></td></tr></table> | |
| 960 | |
| 961 | |
| 962 <a name="msgfilter-Invocation"></a> | |
| 963 <a name="SEC110"></a> | |
| 964 <h2 class="section"> <a href="gettext_toc.html#TOC103">9.4 Invoking the <code>msgfilter</code> Program</a> </h2> | |
| 965 | |
| 966 | |
| 967 <table><tr><td> </td><td><pre class="example">msgfilter [<var>option</var>] <var>filter</var> [<var>filter-option</var>] | |
| 968 </pre></td></tr></table> | |
| 969 | |
| 970 <a name="IDX622"></a> | |
| 971 <p>The <code>msgfilter</code> program applies a filter to all translations of a | |
| 972 translation catalog. | |
| 973 </p> | |
| 974 <a name="IDX623"></a> | |
| 975 <a name="IDX624"></a> | |
| 976 <a name="IDX625"></a> | |
| 977 <a name="IDX626"></a> | |
| 978 <a name="IDX627"></a> | |
| 979 <a name="IDX628"></a> | |
| 980 <a name="IDX629"></a> | |
| 981 <a name="IDX630"></a> | |
| 982 <p>During each <var>filter</var> invocation, the environment variable | |
| 983 <code>MSGFILTER_MSGID</code> is bound to the message's msgid, and the environment | |
| 984 variable <code>MSGFILTER_LOCATION</code> is bound to the location in the PO file | |
| 985 of the message. If the message has a context, the environment variable | |
| 986 <code>MSGFILTER_MSGCTXT</code> is bound to the message's msgctxt, otherwise it is | |
| 987 unbound. If the message has a plural form, environment variable | |
| 988 <code>MSGFILTER_MSGID_PLURAL</code> is bound to the message's msgid_plural and | |
| 989 <code>MSGFILTER_PLURAL_FORM</code> is bound to the order number of the plural | |
| 990 actually processed (starting with 0), otherwise both are unbound. | |
| 991 If the message has a previous msgid (added by <code>msgmerge</code>), | |
| 992 environment variable <code>MSGFILTER_PREV_MSGCTXT</code> is bound to the | |
| 993 message's previous msgctxt, <code>MSGFILTER_PREV_MSGID</code> is bound to | |
| 994 the previous msgid, and <code>MSGFILTER_PREV_MSGID_PLURAL</code> is bound to | |
| 995 the previous msgid_plural. | |
| 996 </p> | |
| 997 | |
| 998 <a name="SEC111"></a> | |
| 999 <h3 class="subsection"> <a href="gettext_toc.html#TOC104">9.4.1 Input file location</a> </h3> | |
| 1000 | |
| 1001 <dl compact="compact"> | |
| 1002 <dt> ‘<samp>-i <var>inputfile</var></samp>’</dt> | |
| 1003 <dt> ‘<samp>--input=<var>inputfile</var></samp>’</dt> | |
| 1004 <dd><a name="IDX631"></a> | |
| 1005 <a name="IDX632"></a> | |
| 1006 <p>Input PO file. | |
| 1007 </p> | |
| 1008 </dd> | |
| 1009 <dt> ‘<samp>-D <var>directory</var></samp>’</dt> | |
| 1010 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt> | |
| 1011 <dd><a name="IDX633"></a> | |
| 1012 <a name="IDX634"></a> | |
| 1013 <p>Add <var>directory</var> to the list of directories. Source files are | |
| 1014 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’ | |
| 1015 file will be written relative to the current directory, though. | |
| 1016 </p> | |
| 1017 </dd> | |
| 1018 </dl> | |
| 1019 | |
| 1020 <p>If no <var>inputfile</var> is given or if it is ‘<samp>-</samp>’, standard input is read. | |
| 1021 </p> | |
| 1022 | |
| 1023 <a name="SEC112"></a> | |
| 1024 <h3 class="subsection"> <a href="gettext_toc.html#TOC105">9.4.2 Output file location</a> </h3> | |
| 1025 | |
| 1026 <dl compact="compact"> | |
| 1027 <dt> ‘<samp>-o <var>file</var></samp>’</dt> | |
| 1028 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt> | |
| 1029 <dd><a name="IDX635"></a> | |
| 1030 <a name="IDX636"></a> | |
| 1031 <p>Write output to specified file. | |
| 1032 </p> | |
| 1033 </dd> | |
| 1034 </dl> | |
| 1035 | |
| 1036 <p>The results are written to standard output if no output file is specified | |
| 1037 or if it is ‘<samp>-</samp>’. | |
| 1038 </p> | |
| 1039 | |
| 1040 <a name="SEC113"></a> | |
| 1041 <h3 class="subsection"> <a href="gettext_toc.html#TOC106">9.4.3 The filter</a> </h3> | |
| 1042 | |
| 1043 <p>The <var>filter</var> can be any program that reads a translation from standard | |
| 1044 input and writes a modified translation to standard output. A frequently | |
| 1045 used filter is ‘<samp>sed</samp>’. A few particular built-in filters are also | |
| 1046 recognized. | |
| 1047 </p> | |
| 1048 <dl compact="compact"> | |
| 1049 <dt> ‘<samp>--newline</samp>’</dt> | |
| 1050 <dd><a name="IDX637"></a> | |
| 1051 <p>Add newline at the end of each input line and also strip the ending | |
| 1052 newline from the output line. | |
| 1053 </p> | |
| 1054 </dd> | |
| 1055 </dl> | |
| 1056 | |
| 1057 <a name="IDX638"></a> | |
| 1058 <p>Note: If the filter is not a built-in filter, you have to care about encodings: | |
| 1059 It is your responsibility to ensure that the <var>filter</var> can cope | |
| 1060 with input encoded in the translation catalog's encoding. If the | |
| 1061 <var>filter</var> wants input in a particular encoding, you can in a first step | |
| 1062 convert the translation catalog to that encoding using the ‘<samp>msgconv</samp>’ | |
| 1063 program, before invoking ‘<samp>msgfilter</samp>’. If the <var>filter</var> wants input | |
| 1064 in the locale's encoding, but you want to avoid the locale's encoding, then | |
| 1065 you can first convert the translation catalog to UTF-8 using the | |
| 1066 ‘<samp>msgconv</samp>’ program and then make ‘<samp>msgfilter</samp>’ work in an UTF-8 | |
| 1067 locale, by using the <code>LC_ALL</code> environment variable. | |
| 1068 </p> | |
| 1069 <a name="IDX639"></a> | |
| 1070 <p>Note: Most translations in a translation catalog don't end with a | |
| 1071 newline character. For this reason, unless the <code>--newline</code> | |
| 1072 option is used, it is important that the <var>filter</var> recognizes its | |
| 1073 last input line even if it ends without a newline, and that it doesn't | |
| 1074 add an undesired trailing newline at the end. The ‘<samp>sed</samp>’ program on | |
| 1075 some platforms is known to ignore the last line of input if it is not | |
| 1076 terminated with a newline. You can use GNU <code>sed</code> instead; it does | |
| 1077 not have this limitation. | |
| 1078 </p> | |
| 1079 | |
| 1080 <a name="SEC114"></a> | |
| 1081 <h3 class="subsection"> <a href="gettext_toc.html#TOC107">9.4.4 Useful <var>filter-option</var>s when the <var>filter</var> is ‘<samp>sed</samp>’</a> </h3> | |
| 1082 | |
| 1083 <dl compact="compact"> | |
| 1084 <dt> ‘<samp>-e <var>script</var></samp>’</dt> | |
| 1085 <dt> ‘<samp>--expression=<var>script</var></samp>’</dt> | |
| 1086 <dd><a name="IDX640"></a> | |
| 1087 <a name="IDX641"></a> | |
| 1088 <p>Add <var>script</var> to the commands to be executed. | |
| 1089 </p> | |
| 1090 </dd> | |
| 1091 <dt> ‘<samp>-f <var>scriptfile</var></samp>’</dt> | |
| 1092 <dt> ‘<samp>--file=<var>scriptfile</var></samp>’</dt> | |
| 1093 <dd><a name="IDX642"></a> | |
| 1094 <a name="IDX643"></a> | |
| 1095 <p>Add the contents of <var>scriptfile</var> to the commands to be executed. | |
| 1096 </p> | |
| 1097 </dd> | |
| 1098 <dt> ‘<samp>-n</samp>’</dt> | |
| 1099 <dt> ‘<samp>--quiet</samp>’</dt> | |
| 1100 <dt> ‘<samp>--silent</samp>’</dt> | |
| 1101 <dd><a name="IDX644"></a> | |
| 1102 <a name="IDX645"></a> | |
| 1103 <a name="IDX646"></a> | |
| 1104 <p>Suppress automatic printing of pattern space. | |
| 1105 </p> | |
| 1106 </dd> | |
| 1107 </dl> | |
| 1108 | |
| 1109 | |
| 1110 <a name="SEC115"></a> | |
| 1111 <h3 class="subsection"> <a href="gettext_toc.html#TOC108">9.4.5 Built-in <var>filter</var>s</a> </h3> | |
| 1112 | |
| 1113 <p>The filter ‘<samp>recode-sr-latin</samp>’ is recognized as a built-in filter. | |
| 1114 The command ‘<samp>recode-sr-latin</samp>’ converts Serbian text, written in the | |
| 1115 Cyrillic script, to the Latin script. | |
| 1116 The command ‘<samp>msgfilter recode-sr-latin</samp>’ applies this conversion to the | |
| 1117 translations of a PO file. Thus, it can be used to convert an ‘<tt>sr.po</tt>’ | |
| 1118 file to an ‘<tt>sr@latin.po</tt>’ file. | |
| 1119 </p> | |
| 1120 <a name="IDX647"></a> | |
| 1121 <p>The filter ‘<samp>quot</samp>’ is recognized as a built-in filter. | |
| 1122 The command ‘<samp>msgfilter quot</samp>’ converts any quotations surrounded | |
| 1123 by a pair of ‘<samp>"</samp>’, ‘<samp>'</samp>’, and ‘<samp>`</samp>’. | |
| 1124 </p> | |
| 1125 <a name="IDX648"></a> | |
| 1126 <p>The filter ‘<samp>boldquot</samp>’ is recognized as a built-in filter. | |
| 1127 The command ‘<samp>msgfilter boldquot</samp>’ converts any quotations | |
| 1128 surrounded by a pair of ‘<samp>"</samp>’, ‘<samp>'</samp>’, and ‘<samp>`</samp>’, also adding the | |
| 1129 VT100 escape sequences to the text to decorate it as bold. | |
| 1130 </p> | |
| 1131 <p>The use of built-in filters is not sensitive to the current locale's encoding. | |
| 1132 Moreover, when used with a built-in filter, ‘<samp>msgfilter</samp>’ can automatically | |
| 1133 convert the message catalog to the UTF-8 encoding when needed. | |
| 1134 </p> | |
| 1135 | |
| 1136 <a name="SEC116"></a> | |
| 1137 <h3 class="subsection"> <a href="gettext_toc.html#TOC109">9.4.6 Input file syntax</a> </h3> | |
| 1138 | |
| 1139 <dl compact="compact"> | |
| 1140 <dt> ‘<samp>-P</samp>’</dt> | |
| 1141 <dt> ‘<samp>--properties-input</samp>’</dt> | |
| 1142 <dd><a name="IDX649"></a> | |
| 1143 <a name="IDX650"></a> | |
| 1144 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> | |
| 1145 syntax, not in PO file syntax. | |
| 1146 </p> | |
| 1147 </dd> | |
| 1148 <dt> ‘<samp>--stringtable-input</samp>’</dt> | |
| 1149 <dd><a name="IDX651"></a> | |
| 1150 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in | |
| 1151 <code>.strings</code> syntax, not in PO file syntax. | |
| 1152 </p> | |
| 1153 </dd> | |
| 1154 </dl> | |
| 1155 | |
| 1156 | |
| 1157 <a name="SEC117"></a> | |
| 1158 <h3 class="subsection"> <a href="gettext_toc.html#TOC110">9.4.7 Output details</a> </h3> | |
| 1159 | |
| 1160 | |
| 1161 <dl compact="compact"> | |
| 1162 <dt> ‘<samp>--color</samp>’</dt> | |
| 1163 <dt> ‘<samp>--color=<var>when</var></samp>’</dt> | |
| 1164 <dd><a name="IDX652"></a> | |
| 1165 <p>Specify whether or when to use colors and other text attributes. | |
| 1166 See <a href="#SEC158">The <code>--color</code> option</a> for details. | |
| 1167 </p> | |
| 1168 </dd> | |
| 1169 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt> | |
| 1170 <dd><a name="IDX653"></a> | |
| 1171 <p>Specify the CSS style rule file to use for <code>--color</code>. | |
| 1172 See <a href="#SEC160">The <code>--style</code> option</a> for details. | |
| 1173 </p> | |
| 1174 </dd> | |
| 1175 <dt> ‘<samp>--force-po</samp>’</dt> | |
| 1176 <dd><a name="IDX654"></a> | |
| 1177 <p>Always write an output file even if it contains no message. | |
| 1178 </p> | |
| 1179 </dd> | |
| 1180 <dt> ‘<samp>--indent</samp>’</dt> | |
| 1181 <dd><a name="IDX655"></a> | |
| 1182 <p>Write the .po file using indented style. | |
| 1183 </p> | |
| 1184 </dd> | |
| 1185 <dt> ‘<samp>--keep-header</samp>’</dt> | |
| 1186 <dd><a name="IDX656"></a> | |
| 1187 <p>Keep the header entry, i.e. the message with ‘<samp>msgid ""</samp>’, unmodified, | |
| 1188 instead of filtering it. By default, the header entry is subject to | |
| 1189 filtering like any other message. | |
| 1190 </p> | |
| 1191 </dd> | |
| 1192 <dt> ‘<samp>--no-location</samp>’</dt> | |
| 1193 <dd><a name="IDX657"></a> | |
| 1194 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines. | |
| 1195 </p> | |
| 1196 </dd> | |
| 1197 <dt> ‘<samp>-n</samp>’</dt> | |
| 1198 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt> | |
| 1199 <dd><a name="IDX658"></a> | |
| 1200 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default). | |
| 1201 </p> | |
| 1202 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or | |
| 1203 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the | |
| 1204 lines with both file name and line number. If it is ‘<samp>file</samp>’, the | |
| 1205 line number part is omitted. If it is ‘<samp>never</samp>’, it completely | |
| 1206 suppresses the lines (same as <code>--no-location</code>). | |
| 1207 </p> | |
| 1208 </dd> | |
| 1209 <dt> ‘<samp>--strict</samp>’</dt> | |
| 1210 <dd><a name="IDX659"></a> | |
| 1211 <p>Write out a strict Uniforum conforming PO file. Note that this | |
| 1212 Uniforum format should be avoided because it doesn't support the | |
| 1213 GNU extensions. | |
| 1214 </p> | |
| 1215 </dd> | |
| 1216 <dt> ‘<samp>-p</samp>’</dt> | |
| 1217 <dt> ‘<samp>--properties-output</samp>’</dt> | |
| 1218 <dd><a name="IDX660"></a> | |
| 1219 <a name="IDX661"></a> | |
| 1220 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note | |
| 1221 that this file format doesn't support plural forms and silently drops | |
| 1222 obsolete messages. | |
| 1223 </p> | |
| 1224 </dd> | |
| 1225 <dt> ‘<samp>--stringtable-output</samp>’</dt> | |
| 1226 <dd><a name="IDX662"></a> | |
| 1227 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. | |
| 1228 Note that this file format doesn't support plural forms. | |
| 1229 </p> | |
| 1230 </dd> | |
| 1231 <dt> ‘<samp>-w <var>number</var></samp>’</dt> | |
| 1232 <dt> ‘<samp>--width=<var>number</var></samp>’</dt> | |
| 1233 <dd><a name="IDX663"></a> | |
| 1234 <a name="IDX664"></a> | |
| 1235 <p>Set the output page width. Long strings in the output files will be | |
| 1236 split across multiple lines in order to ensure that each line's width | |
| 1237 (= number of screen columns) is less or equal to the given <var>number</var>. | |
| 1238 </p> | |
| 1239 </dd> | |
| 1240 <dt> ‘<samp>--no-wrap</samp>’</dt> | |
| 1241 <dd><a name="IDX665"></a> | |
| 1242 <p>Do not break long message lines. Message lines whose width exceeds the | |
| 1243 output page width will not be split into several lines. Only file reference | |
| 1244 lines which are wider than the output page width will be split. | |
| 1245 </p> | |
| 1246 </dd> | |
| 1247 <dt> ‘<samp>-s</samp>’</dt> | |
| 1248 <dt> ‘<samp>--sort-output</samp>’</dt> | |
| 1249 <dd><a name="IDX666"></a> | |
| 1250 <a name="IDX667"></a> | |
| 1251 <p>Generate sorted output. Note that using this option makes it much harder | |
| 1252 for the translator to understand each message's context. | |
| 1253 </p> | |
| 1254 </dd> | |
| 1255 <dt> ‘<samp>-F</samp>’</dt> | |
| 1256 <dt> ‘<samp>--sort-by-file</samp>’</dt> | |
| 1257 <dd><a name="IDX668"></a> | |
| 1258 <a name="IDX669"></a> | |
| 1259 <p>Sort output by file location. | |
| 1260 </p> | |
| 1261 </dd> | |
| 1262 </dl> | |
| 1263 | |
| 1264 | |
| 1265 <a name="SEC118"></a> | |
| 1266 <h3 class="subsection"> <a href="gettext_toc.html#TOC111">9.4.8 Informative output</a> </h3> | |
| 1267 | |
| 1268 <dl compact="compact"> | |
| 1269 <dt> ‘<samp>-h</samp>’</dt> | |
| 1270 <dt> ‘<samp>--help</samp>’</dt> | |
| 1271 <dd><a name="IDX670"></a> | |
| 1272 <a name="IDX671"></a> | |
| 1273 <p>Display this help and exit. | |
| 1274 </p> | |
| 1275 </dd> | |
| 1276 <dt> ‘<samp>-V</samp>’</dt> | |
| 1277 <dt> ‘<samp>--version</samp>’</dt> | |
| 1278 <dd><a name="IDX672"></a> | |
| 1279 <a name="IDX673"></a> | |
| 1280 <p>Output version information and exit. | |
| 1281 </p> | |
| 1282 </dd> | |
| 1283 </dl> | |
| 1284 | |
| 1285 | |
| 1286 <a name="SEC119"></a> | |
| 1287 <h3 class="subsection"> <a href="gettext_toc.html#TOC112">9.4.9 Examples</a> </h3> | |
| 1288 | |
| 1289 <p>To convert German translations to Swiss orthography (in an UTF-8 locale): | |
| 1290 </p> | |
| 1291 <table><tr><td> </td><td><pre class="smallexample">msgconv -t UTF-8 de.po | msgfilter sed -e 's/ß/ss/g' | |
| 1292 </pre></td></tr></table> | |
| 1293 | |
| 1294 <p>To convert Serbian translations in Cyrillic script to Latin script: | |
| 1295 </p> | |
| 1296 <table><tr><td> </td><td><pre class="smallexample">msgfilter recode-sr-latin < sr.po | |
| 1297 </pre></td></tr></table> | |
| 1298 | |
| 1299 | |
| 1300 <a name="msguniq-Invocation"></a> | |
| 1301 <a name="SEC120"></a> | |
| 1302 <h2 class="section"> <a href="gettext_toc.html#TOC113">9.5 Invoking the <code>msguniq</code> Program</a> </h2> | |
| 1303 | |
| 1304 | |
| 1305 <table><tr><td> </td><td><pre class="example">msguniq [<var>option</var>] [<var>inputfile</var>] | |
| 1306 </pre></td></tr></table> | |
| 1307 | |
| 1308 <a name="IDX674"></a> | |
| 1309 <a name="IDX675"></a> | |
| 1310 <p>The <code>msguniq</code> program unifies duplicate translations in a translation | |
| 1311 catalog. It finds duplicate translations of the same message ID. Such | |
| 1312 duplicates are invalid input for other programs like <code>msgfmt</code>, | |
| 1313 <code>msgmerge</code> or <code>msgcat</code>. By default, duplicates are merged | |
| 1314 together. When using the ‘<samp>--repeated</samp>’ option, only duplicates are | |
| 1315 output, and all other messages are discarded. Comments and extracted | |
| 1316 comments will be cumulated, except that if ‘<samp>--use-first</samp>’ is | |
| 1317 specified, they will be taken from the first translation. File positions | |
| 1318 will be cumulated. When using the ‘<samp>--unique</samp>’ option, duplicates are | |
| 1319 discarded. | |
| 1320 </p> | |
| 1321 | |
| 1322 <a name="SEC121"></a> | |
| 1323 <h3 class="subsection"> <a href="gettext_toc.html#TOC114">9.5.1 Input file location</a> </h3> | |
| 1324 | |
| 1325 <dl compact="compact"> | |
| 1326 <dt> ‘<samp><var>inputfile</var></samp>’</dt> | |
| 1327 <dd><p>Input PO file. | |
| 1328 </p> | |
| 1329 </dd> | |
| 1330 <dt> ‘<samp>-D <var>directory</var></samp>’</dt> | |
| 1331 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt> | |
| 1332 <dd><a name="IDX676"></a> | |
| 1333 <a name="IDX677"></a> | |
| 1334 <p>Add <var>directory</var> to the list of directories. Source files are | |
| 1335 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’ | |
| 1336 file will be written relative to the current directory, though. | |
| 1337 </p> | |
| 1338 </dd> | |
| 1339 </dl> | |
| 1340 | |
| 1341 <p>If no <var>inputfile</var> is given or if it is ‘<samp>-</samp>’, standard input is read. | |
| 1342 </p> | |
| 1343 | |
| 1344 <a name="SEC122"></a> | |
| 1345 <h3 class="subsection"> <a href="gettext_toc.html#TOC115">9.5.2 Output file location</a> </h3> | |
| 1346 | |
| 1347 <dl compact="compact"> | |
| 1348 <dt> ‘<samp>-o <var>file</var></samp>’</dt> | |
| 1349 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt> | |
| 1350 <dd><a name="IDX678"></a> | |
| 1351 <a name="IDX679"></a> | |
| 1352 <p>Write output to specified file. | |
| 1353 </p> | |
| 1354 </dd> | |
| 1355 </dl> | |
| 1356 | |
| 1357 <p>The results are written to standard output if no output file is specified | |
| 1358 or if it is ‘<samp>-</samp>’. | |
| 1359 </p> | |
| 1360 | |
| 1361 <a name="SEC123"></a> | |
| 1362 <h3 class="subsection"> <a href="gettext_toc.html#TOC116">9.5.3 Message selection</a> </h3> | |
| 1363 | |
| 1364 <dl compact="compact"> | |
| 1365 <dt> ‘<samp>-d</samp>’</dt> | |
| 1366 <dt> ‘<samp>--repeated</samp>’</dt> | |
| 1367 <dd><a name="IDX680"></a> | |
| 1368 <a name="IDX681"></a> | |
| 1369 <p>Print only duplicates. | |
| 1370 </p> | |
| 1371 </dd> | |
| 1372 <dt> ‘<samp>-u</samp>’</dt> | |
| 1373 <dt> ‘<samp>--unique</samp>’</dt> | |
| 1374 <dd><a name="IDX682"></a> | |
| 1375 <a name="IDX683"></a> | |
| 1376 <p>Print only unique messages, discard duplicates. | |
| 1377 </p> | |
| 1378 </dd> | |
| 1379 </dl> | |
| 1380 | |
| 1381 | |
| 1382 <a name="SEC124"></a> | |
| 1383 <h3 class="subsection"> <a href="gettext_toc.html#TOC117">9.5.4 Input file syntax</a> </h3> | |
| 1384 | |
| 1385 <dl compact="compact"> | |
| 1386 <dt> ‘<samp>-P</samp>’</dt> | |
| 1387 <dt> ‘<samp>--properties-input</samp>’</dt> | |
| 1388 <dd><a name="IDX684"></a> | |
| 1389 <a name="IDX685"></a> | |
| 1390 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> | |
| 1391 syntax, not in PO file syntax. | |
| 1392 </p> | |
| 1393 </dd> | |
| 1394 <dt> ‘<samp>--stringtable-input</samp>’</dt> | |
| 1395 <dd><a name="IDX686"></a> | |
| 1396 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in | |
| 1397 <code>.strings</code> syntax, not in PO file syntax. | |
| 1398 </p> | |
| 1399 </dd> | |
| 1400 </dl> | |
| 1401 | |
| 1402 | |
| 1403 <a name="SEC125"></a> | |
| 1404 <h3 class="subsection"> <a href="gettext_toc.html#TOC118">9.5.5 Output details</a> </h3> | |
| 1405 | |
| 1406 | |
| 1407 <dl compact="compact"> | |
| 1408 <dt> ‘<samp>-t</samp>’</dt> | |
| 1409 <dt> ‘<samp>--to-code=<var>name</var></samp>’</dt> | |
| 1410 <dd><a name="IDX687"></a> | |
| 1411 <a name="IDX688"></a> | |
| 1412 <p>Specify encoding for output. | |
| 1413 </p> | |
| 1414 </dd> | |
| 1415 <dt> ‘<samp>--use-first</samp>’</dt> | |
| 1416 <dd><a name="IDX689"></a> | |
| 1417 <p>Use first available translation for each message. Don't merge several | |
| 1418 translations into one. | |
| 1419 </p> | |
| 1420 </dd> | |
| 1421 <dt> ‘<samp>--color</samp>’</dt> | |
| 1422 <dt> ‘<samp>--color=<var>when</var></samp>’</dt> | |
| 1423 <dd><a name="IDX690"></a> | |
| 1424 <p>Specify whether or when to use colors and other text attributes. | |
| 1425 See <a href="#SEC158">The <code>--color</code> option</a> for details. | |
| 1426 </p> | |
| 1427 </dd> | |
| 1428 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt> | |
| 1429 <dd><a name="IDX691"></a> | |
| 1430 <p>Specify the CSS style rule file to use for <code>--color</code>. | |
| 1431 See <a href="#SEC160">The <code>--style</code> option</a> for details. | |
| 1432 </p> | |
| 1433 </dd> | |
| 1434 <dt> ‘<samp>--force-po</samp>’</dt> | |
| 1435 <dd><a name="IDX692"></a> | |
| 1436 <p>Always write an output file even if it contains no message. | |
| 1437 </p> | |
| 1438 </dd> | |
| 1439 <dt> ‘<samp>-i</samp>’</dt> | |
| 1440 <dt> ‘<samp>--indent</samp>’</dt> | |
| 1441 <dd><a name="IDX693"></a> | |
| 1442 <a name="IDX694"></a> | |
| 1443 <p>Write the .po file using indented style. | |
| 1444 </p> | |
| 1445 </dd> | |
| 1446 <dt> ‘<samp>--no-location</samp>’</dt> | |
| 1447 <dd><a name="IDX695"></a> | |
| 1448 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines. | |
| 1449 </p> | |
| 1450 </dd> | |
| 1451 <dt> ‘<samp>-n</samp>’</dt> | |
| 1452 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt> | |
| 1453 <dd><a name="IDX696"></a> | |
| 1454 <a name="IDX697"></a> | |
| 1455 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default). | |
| 1456 </p> | |
| 1457 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or | |
| 1458 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the | |
| 1459 lines with both file name and line number. If it is ‘<samp>file</samp>’, the | |
| 1460 line number part is omitted. If it is ‘<samp>never</samp>’, it completely | |
| 1461 suppresses the lines (same as <code>--no-location</code>). | |
| 1462 </p> | |
| 1463 </dd> | |
| 1464 <dt> ‘<samp>--strict</samp>’</dt> | |
| 1465 <dd><a name="IDX698"></a> | |
| 1466 <p>Write out a strict Uniforum conforming PO file. Note that this | |
| 1467 Uniforum format should be avoided because it doesn't support the | |
| 1468 GNU extensions. | |
| 1469 </p> | |
| 1470 </dd> | |
| 1471 <dt> ‘<samp>-p</samp>’</dt> | |
| 1472 <dt> ‘<samp>--properties-output</samp>’</dt> | |
| 1473 <dd><a name="IDX699"></a> | |
| 1474 <a name="IDX700"></a> | |
| 1475 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note | |
| 1476 that this file format doesn't support plural forms and silently drops | |
| 1477 obsolete messages. | |
| 1478 </p> | |
| 1479 </dd> | |
| 1480 <dt> ‘<samp>--stringtable-output</samp>’</dt> | |
| 1481 <dd><a name="IDX701"></a> | |
| 1482 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. | |
| 1483 Note that this file format doesn't support plural forms. | |
| 1484 </p> | |
| 1485 </dd> | |
| 1486 <dt> ‘<samp>-w <var>number</var></samp>’</dt> | |
| 1487 <dt> ‘<samp>--width=<var>number</var></samp>’</dt> | |
| 1488 <dd><a name="IDX702"></a> | |
| 1489 <a name="IDX703"></a> | |
| 1490 <p>Set the output page width. Long strings in the output files will be | |
| 1491 split across multiple lines in order to ensure that each line's width | |
| 1492 (= number of screen columns) is less or equal to the given <var>number</var>. | |
| 1493 </p> | |
| 1494 </dd> | |
| 1495 <dt> ‘<samp>--no-wrap</samp>’</dt> | |
| 1496 <dd><a name="IDX704"></a> | |
| 1497 <p>Do not break long message lines. Message lines whose width exceeds the | |
| 1498 output page width will not be split into several lines. Only file reference | |
| 1499 lines which are wider than the output page width will be split. | |
| 1500 </p> | |
| 1501 </dd> | |
| 1502 <dt> ‘<samp>-s</samp>’</dt> | |
| 1503 <dt> ‘<samp>--sort-output</samp>’</dt> | |
| 1504 <dd><a name="IDX705"></a> | |
| 1505 <a name="IDX706"></a> | |
| 1506 <p>Generate sorted output. Note that using this option makes it much harder | |
| 1507 for the translator to understand each message's context. | |
| 1508 </p> | |
| 1509 </dd> | |
| 1510 <dt> ‘<samp>-F</samp>’</dt> | |
| 1511 <dt> ‘<samp>--sort-by-file</samp>’</dt> | |
| 1512 <dd><a name="IDX707"></a> | |
| 1513 <a name="IDX708"></a> | |
| 1514 <p>Sort output by file location. | |
| 1515 </p> | |
| 1516 </dd> | |
| 1517 </dl> | |
| 1518 | |
| 1519 | |
| 1520 <a name="SEC126"></a> | |
| 1521 <h3 class="subsection"> <a href="gettext_toc.html#TOC119">9.5.6 Informative output</a> </h3> | |
| 1522 | |
| 1523 <dl compact="compact"> | |
| 1524 <dt> ‘<samp>-h</samp>’</dt> | |
| 1525 <dt> ‘<samp>--help</samp>’</dt> | |
| 1526 <dd><a name="IDX709"></a> | |
| 1527 <a name="IDX710"></a> | |
| 1528 <p>Display this help and exit. | |
| 1529 </p> | |
| 1530 </dd> | |
| 1531 <dt> ‘<samp>-V</samp>’</dt> | |
| 1532 <dt> ‘<samp>--version</samp>’</dt> | |
| 1533 <dd><a name="IDX711"></a> | |
| 1534 <a name="IDX712"></a> | |
| 1535 <p>Output version information and exit. | |
| 1536 </p> | |
| 1537 </dd> | |
| 1538 </dl> | |
| 1539 | |
| 1540 | |
| 1541 <a name="msgcomm-Invocation"></a> | |
| 1542 <a name="SEC127"></a> | |
| 1543 <h2 class="section"> <a href="gettext_toc.html#TOC120">9.6 Invoking the <code>msgcomm</code> Program</a> </h2> | |
| 1544 | |
| 1545 | |
| 1546 <table><tr><td> </td><td><pre class="example">msgcomm [<var>option</var>] [<var>inputfile</var>]... | |
| 1547 </pre></td></tr></table> | |
| 1548 | |
| 1549 <a name="IDX713"></a> | |
| 1550 <p>The <code>msgcomm</code> program finds messages which are common to two or more | |
| 1551 of the specified PO files. | |
| 1552 By using the <code>--more-than</code> option, greater commonality may be requested | |
| 1553 before messages are printed. Conversely, the <code>--less-than</code> option may be | |
| 1554 used to specify less commonality before messages are printed (i.e. | |
| 1555 ‘<samp>--less-than=2</samp>’ will only print the unique messages). Translations, | |
| 1556 comments and extracted comments will be preserved, but only from the first | |
| 1557 PO file to define them. File positions from all PO files will be | |
| 1558 cumulated. | |
| 1559 </p> | |
| 1560 | |
| 1561 <a name="SEC128"></a> | |
| 1562 <h3 class="subsection"> <a href="gettext_toc.html#TOC121">9.6.1 Input file location</a> </h3> | |
| 1563 | |
| 1564 <dl compact="compact"> | |
| 1565 <dt> ‘<samp><var>inputfile</var> …</samp>’</dt> | |
| 1566 <dd><p>Input files. | |
| 1567 </p> | |
| 1568 </dd> | |
| 1569 <dt> ‘<samp>-f <var>file</var></samp>’</dt> | |
| 1570 <dt> ‘<samp>--files-from=<var>file</var></samp>’</dt> | |
| 1571 <dd><a name="IDX714"></a> | |
| 1572 <a name="IDX715"></a> | |
| 1573 <p>Read the names of the input files from <var>file</var> instead of getting | |
| 1574 them from the command line. | |
| 1575 </p> | |
| 1576 </dd> | |
| 1577 <dt> ‘<samp>-D <var>directory</var></samp>’</dt> | |
| 1578 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt> | |
| 1579 <dd><a name="IDX716"></a> | |
| 1580 <a name="IDX717"></a> | |
| 1581 <p>Add <var>directory</var> to the list of directories. Source files are | |
| 1582 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’ | |
| 1583 file will be written relative to the current directory, though. | |
| 1584 </p> | |
| 1585 </dd> | |
| 1586 </dl> | |
| 1587 | |
| 1588 <p>If <var>inputfile</var> is ‘<samp>-</samp>’, standard input is read. | |
| 1589 </p> | |
| 1590 | |
| 1591 <a name="SEC129"></a> | |
| 1592 <h3 class="subsection"> <a href="gettext_toc.html#TOC122">9.6.2 Output file location</a> </h3> | |
| 1593 | |
| 1594 <dl compact="compact"> | |
| 1595 <dt> ‘<samp>-o <var>file</var></samp>’</dt> | |
| 1596 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt> | |
| 1597 <dd><a name="IDX718"></a> | |
| 1598 <a name="IDX719"></a> | |
| 1599 <p>Write output to specified file. | |
| 1600 </p> | |
| 1601 </dd> | |
| 1602 </dl> | |
| 1603 | |
| 1604 <p>The results are written to standard output if no output file is specified | |
| 1605 or if it is ‘<samp>-</samp>’. | |
| 1606 </p> | |
| 1607 | |
| 1608 <a name="SEC130"></a> | |
| 1609 <h3 class="subsection"> <a href="gettext_toc.html#TOC123">9.6.3 Message selection</a> </h3> | |
| 1610 | |
| 1611 <dl compact="compact"> | |
| 1612 <dt> ‘<samp>-< <var>number</var></samp>’</dt> | |
| 1613 <dt> ‘<samp>--less-than=<var>number</var></samp>’</dt> | |
| 1614 <dd><a name="IDX720"></a> | |
| 1615 <a name="IDX721"></a> | |
| 1616 <p>Print messages with less than <var>number</var> definitions, defaults to infinite | |
| 1617 if not set. | |
| 1618 </p> | |
| 1619 </dd> | |
| 1620 <dt> ‘<samp>-> <var>number</var></samp>’</dt> | |
| 1621 <dt> ‘<samp>--more-than=<var>number</var></samp>’</dt> | |
| 1622 <dd><a name="IDX722"></a> | |
| 1623 <a name="IDX723"></a> | |
| 1624 <p>Print messages with more than <var>number</var> definitions, defaults to 1 if not | |
| 1625 set. | |
| 1626 </p> | |
| 1627 </dd> | |
| 1628 <dt> ‘<samp>-u</samp>’</dt> | |
| 1629 <dt> ‘<samp>--unique</samp>’</dt> | |
| 1630 <dd><a name="IDX724"></a> | |
| 1631 <a name="IDX725"></a> | |
| 1632 <p>Shorthand for ‘<samp>--less-than=2</samp>’. Requests that only unique messages be | |
| 1633 printed. | |
| 1634 </p> | |
| 1635 </dd> | |
| 1636 </dl> | |
| 1637 | |
| 1638 | |
| 1639 <a name="SEC131"></a> | |
| 1640 <h3 class="subsection"> <a href="gettext_toc.html#TOC124">9.6.4 Input file syntax</a> </h3> | |
| 1641 | |
| 1642 <dl compact="compact"> | |
| 1643 <dt> ‘<samp>-P</samp>’</dt> | |
| 1644 <dt> ‘<samp>--properties-input</samp>’</dt> | |
| 1645 <dd><a name="IDX726"></a> | |
| 1646 <a name="IDX727"></a> | |
| 1647 <p>Assume the input files are Java ResourceBundles in Java <code>.properties</code> | |
| 1648 syntax, not in PO file syntax. | |
| 1649 </p> | |
| 1650 </dd> | |
| 1651 <dt> ‘<samp>--stringtable-input</samp>’</dt> | |
| 1652 <dd><a name="IDX728"></a> | |
| 1653 <p>Assume the input files are NeXTstep/GNUstep localized resource files in | |
| 1654 <code>.strings</code> syntax, not in PO file syntax. | |
| 1655 </p> | |
| 1656 </dd> | |
| 1657 </dl> | |
| 1658 | |
| 1659 | |
| 1660 <a name="SEC132"></a> | |
| 1661 <h3 class="subsection"> <a href="gettext_toc.html#TOC125">9.6.5 Output details</a> </h3> | |
| 1662 | |
| 1663 | |
| 1664 <dl compact="compact"> | |
| 1665 <dt> ‘<samp>--color</samp>’</dt> | |
| 1666 <dt> ‘<samp>--color=<var>when</var></samp>’</dt> | |
| 1667 <dd><a name="IDX729"></a> | |
| 1668 <p>Specify whether or when to use colors and other text attributes. | |
| 1669 See <a href="#SEC158">The <code>--color</code> option</a> for details. | |
| 1670 </p> | |
| 1671 </dd> | |
| 1672 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt> | |
| 1673 <dd><a name="IDX730"></a> | |
| 1674 <p>Specify the CSS style rule file to use for <code>--color</code>. | |
| 1675 See <a href="#SEC160">The <code>--style</code> option</a> for details. | |
| 1676 </p> | |
| 1677 </dd> | |
| 1678 <dt> ‘<samp>--force-po</samp>’</dt> | |
| 1679 <dd><a name="IDX731"></a> | |
| 1680 <p>Always write an output file even if it contains no message. | |
| 1681 </p> | |
| 1682 </dd> | |
| 1683 <dt> ‘<samp>-i</samp>’</dt> | |
| 1684 <dt> ‘<samp>--indent</samp>’</dt> | |
| 1685 <dd><a name="IDX732"></a> | |
| 1686 <a name="IDX733"></a> | |
| 1687 <p>Write the .po file using indented style. | |
| 1688 </p> | |
| 1689 </dd> | |
| 1690 <dt> ‘<samp>--no-location</samp>’</dt> | |
| 1691 <dd><a name="IDX734"></a> | |
| 1692 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines. | |
| 1693 </p> | |
| 1694 </dd> | |
| 1695 <dt> ‘<samp>-n</samp>’</dt> | |
| 1696 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt> | |
| 1697 <dd><a name="IDX735"></a> | |
| 1698 <a name="IDX736"></a> | |
| 1699 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default). | |
| 1700 </p> | |
| 1701 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or | |
| 1702 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the | |
| 1703 lines with both file name and line number. If it is ‘<samp>file</samp>’, the | |
| 1704 line number part is omitted. If it is ‘<samp>never</samp>’, it completely | |
| 1705 suppresses the lines (same as <code>--no-location</code>). | |
| 1706 </p> | |
| 1707 </dd> | |
| 1708 <dt> ‘<samp>--strict</samp>’</dt> | |
| 1709 <dd><a name="IDX737"></a> | |
| 1710 <p>Write out a strict Uniforum conforming PO file. Note that this | |
| 1711 Uniforum format should be avoided because it doesn't support the | |
| 1712 GNU extensions. | |
| 1713 </p> | |
| 1714 </dd> | |
| 1715 <dt> ‘<samp>-p</samp>’</dt> | |
| 1716 <dt> ‘<samp>--properties-output</samp>’</dt> | |
| 1717 <dd><a name="IDX738"></a> | |
| 1718 <a name="IDX739"></a> | |
| 1719 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note | |
| 1720 that this file format doesn't support plural forms and silently drops | |
| 1721 obsolete messages. | |
| 1722 </p> | |
| 1723 </dd> | |
| 1724 <dt> ‘<samp>--stringtable-output</samp>’</dt> | |
| 1725 <dd><a name="IDX740"></a> | |
| 1726 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. | |
| 1727 Note that this file format doesn't support plural forms. | |
| 1728 </p> | |
| 1729 </dd> | |
| 1730 <dt> ‘<samp>-w <var>number</var></samp>’</dt> | |
| 1731 <dt> ‘<samp>--width=<var>number</var></samp>’</dt> | |
| 1732 <dd><a name="IDX741"></a> | |
| 1733 <a name="IDX742"></a> | |
| 1734 <p>Set the output page width. Long strings in the output files will be | |
| 1735 split across multiple lines in order to ensure that each line's width | |
| 1736 (= number of screen columns) is less or equal to the given <var>number</var>. | |
| 1737 </p> | |
| 1738 </dd> | |
| 1739 <dt> ‘<samp>--no-wrap</samp>’</dt> | |
| 1740 <dd><a name="IDX743"></a> | |
| 1741 <p>Do not break long message lines. Message lines whose width exceeds the | |
| 1742 output page width will not be split into several lines. Only file reference | |
| 1743 lines which are wider than the output page width will be split. | |
| 1744 </p> | |
| 1745 </dd> | |
| 1746 <dt> ‘<samp>-s</samp>’</dt> | |
| 1747 <dt> ‘<samp>--sort-output</samp>’</dt> | |
| 1748 <dd><a name="IDX744"></a> | |
| 1749 <a name="IDX745"></a> | |
| 1750 <p>Generate sorted output. Note that using this option makes it much harder | |
| 1751 for the translator to understand each message's context. | |
| 1752 </p> | |
| 1753 </dd> | |
| 1754 <dt> ‘<samp>-F</samp>’</dt> | |
| 1755 <dt> ‘<samp>--sort-by-file</samp>’</dt> | |
| 1756 <dd><a name="IDX746"></a> | |
| 1757 <a name="IDX747"></a> | |
| 1758 <p>Sort output by file location. | |
| 1759 </p> | |
| 1760 </dd> | |
| 1761 <dt> ‘<samp>--omit-header</samp>’</dt> | |
| 1762 <dd><a name="IDX748"></a> | |
| 1763 <p>Don't write header with ‘<samp>msgid ""</samp>’ entry. | |
| 1764 </p> | |
| 1765 </dd> | |
| 1766 </dl> | |
| 1767 | |
| 1768 | |
| 1769 <a name="SEC133"></a> | |
| 1770 <h3 class="subsection"> <a href="gettext_toc.html#TOC126">9.6.6 Informative output</a> </h3> | |
| 1771 | |
| 1772 <dl compact="compact"> | |
| 1773 <dt> ‘<samp>-h</samp>’</dt> | |
| 1774 <dt> ‘<samp>--help</samp>’</dt> | |
| 1775 <dd><a name="IDX749"></a> | |
| 1776 <a name="IDX750"></a> | |
| 1777 <p>Display this help and exit. | |
| 1778 </p> | |
| 1779 </dd> | |
| 1780 <dt> ‘<samp>-V</samp>’</dt> | |
| 1781 <dt> ‘<samp>--version</samp>’</dt> | |
| 1782 <dd><a name="IDX751"></a> | |
| 1783 <a name="IDX752"></a> | |
| 1784 <p>Output version information and exit. | |
| 1785 </p> | |
| 1786 </dd> | |
| 1787 </dl> | |
| 1788 | |
| 1789 | |
| 1790 <a name="msgcmp-Invocation"></a> | |
| 1791 <a name="SEC134"></a> | |
| 1792 <h2 class="section"> <a href="gettext_toc.html#TOC127">9.7 Invoking the <code>msgcmp</code> Program</a> </h2> | |
| 1793 | |
| 1794 | |
| 1795 <table><tr><td> </td><td><pre class="example">msgcmp [<var>option</var>] <var>def</var>.po <var>ref</var>.pot | |
| 1796 </pre></td></tr></table> | |
| 1797 | |
| 1798 <a name="IDX753"></a> | |
| 1799 <p>The <code>msgcmp</code> program compares two Uniforum style .po files to check that | |
| 1800 both contain the same set of msgid strings. The <var>def</var>.po file is an | |
| 1801 existing PO file with the translations. The <var>ref</var>.pot file is the last | |
| 1802 created PO file, or a PO Template file (generally created by <code>xgettext</code>). | |
| 1803 This is useful for checking that you have translated each and every message | |
| 1804 in your program. Where an exact match cannot be found, fuzzy matching is | |
| 1805 used to produce better diagnostics. | |
| 1806 </p> | |
| 1807 | |
| 1808 <a name="SEC135"></a> | |
| 1809 <h3 class="subsection"> <a href="gettext_toc.html#TOC128">9.7.1 Input file location</a> </h3> | |
| 1810 | |
| 1811 <dl compact="compact"> | |
| 1812 <dt> ‘<samp><var>def</var>.po</samp>’</dt> | |
| 1813 <dd><p>Translations. | |
| 1814 </p> | |
| 1815 </dd> | |
| 1816 <dt> ‘<samp><var>ref</var>.pot</samp>’</dt> | |
| 1817 <dd><p>References to the sources. | |
| 1818 </p> | |
| 1819 </dd> | |
| 1820 <dt> ‘<samp>-D <var>directory</var></samp>’</dt> | |
| 1821 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt> | |
| 1822 <dd><a name="IDX754"></a> | |
| 1823 <a name="IDX755"></a> | |
| 1824 <p>Add <var>directory</var> to the list of directories. Source files are | |
| 1825 searched relative to this list of directories. | |
| 1826 </p> | |
| 1827 </dd> | |
| 1828 </dl> | |
| 1829 | |
| 1830 | |
| 1831 <a name="SEC136"></a> | |
| 1832 <h3 class="subsection"> <a href="gettext_toc.html#TOC129">9.7.2 Operation modifiers</a> </h3> | |
| 1833 | |
| 1834 <dl compact="compact"> | |
| 1835 <dt> ‘<samp>-m</samp>’</dt> | |
| 1836 <dt> ‘<samp>--multi-domain</samp>’</dt> | |
| 1837 <dd><a name="IDX756"></a> | |
| 1838 <a name="IDX757"></a> | |
| 1839 <p>Apply <var>ref</var>.pot to each of the domains in <var>def</var>.po. | |
| 1840 </p> | |
| 1841 </dd> | |
| 1842 <dt> ‘<samp>-N</samp>’</dt> | |
| 1843 <dt> ‘<samp>--no-fuzzy-matching</samp>’</dt> | |
| 1844 <dd><a name="IDX758"></a> | |
| 1845 <a name="IDX759"></a> | |
| 1846 <p>Do not use fuzzy matching when an exact match is not found. This may speed | |
| 1847 up the operation considerably. | |
| 1848 </p> | |
| 1849 </dd> | |
| 1850 <dt> ‘<samp>--use-fuzzy</samp>’</dt> | |
| 1851 <dd><a name="IDX760"></a> | |
| 1852 <p>Consider fuzzy messages in the <var>def</var>.po file like translated messages. | |
| 1853 Note that using this option is usually wrong, because fuzzy messages are | |
| 1854 exactly those which have not been validated by a human translator. | |
| 1855 </p> | |
| 1856 </dd> | |
| 1857 <dt> ‘<samp>--use-untranslated</samp>’</dt> | |
| 1858 <dd><a name="IDX761"></a> | |
| 1859 <p>Consider untranslated messages in the <var>def</var>.po file like translated | |
| 1860 messages. Note that using this option is usually wrong. | |
| 1861 </p> | |
| 1862 </dd> | |
| 1863 </dl> | |
| 1864 | |
| 1865 | |
| 1866 <a name="SEC137"></a> | |
| 1867 <h3 class="subsection"> <a href="gettext_toc.html#TOC130">9.7.3 Input file syntax</a> </h3> | |
| 1868 | |
| 1869 <dl compact="compact"> | |
| 1870 <dt> ‘<samp>-P</samp>’</dt> | |
| 1871 <dt> ‘<samp>--properties-input</samp>’</dt> | |
| 1872 <dd><a name="IDX762"></a> | |
| 1873 <a name="IDX763"></a> | |
| 1874 <p>Assume the input files are Java ResourceBundles in Java <code>.properties</code> | |
| 1875 syntax, not in PO file syntax. | |
| 1876 </p> | |
| 1877 </dd> | |
| 1878 <dt> ‘<samp>--stringtable-input</samp>’</dt> | |
| 1879 <dd><a name="IDX764"></a> | |
| 1880 <p>Assume the input files are NeXTstep/GNUstep localized resource files in | |
| 1881 <code>.strings</code> syntax, not in PO file syntax. | |
| 1882 </p> | |
| 1883 </dd> | |
| 1884 </dl> | |
| 1885 | |
| 1886 | |
| 1887 <a name="SEC138"></a> | |
| 1888 <h3 class="subsection"> <a href="gettext_toc.html#TOC131">9.7.4 Informative output</a> </h3> | |
| 1889 | |
| 1890 <dl compact="compact"> | |
| 1891 <dt> ‘<samp>-h</samp>’</dt> | |
| 1892 <dt> ‘<samp>--help</samp>’</dt> | |
| 1893 <dd><a name="IDX765"></a> | |
| 1894 <a name="IDX766"></a> | |
| 1895 <p>Display this help and exit. | |
| 1896 </p> | |
| 1897 </dd> | |
| 1898 <dt> ‘<samp>-V</samp>’</dt> | |
| 1899 <dt> ‘<samp>--version</samp>’</dt> | |
| 1900 <dd><a name="IDX767"></a> | |
| 1901 <a name="IDX768"></a> | |
| 1902 <p>Output version information and exit. | |
| 1903 </p> | |
| 1904 </dd> | |
| 1905 </dl> | |
| 1906 | |
| 1907 | |
| 1908 <a name="msgattrib-Invocation"></a> | |
| 1909 <a name="SEC139"></a> | |
| 1910 <h2 class="section"> <a href="gettext_toc.html#TOC132">9.8 Invoking the <code>msgattrib</code> Program</a> </h2> | |
| 1911 | |
| 1912 | |
| 1913 <table><tr><td> </td><td><pre class="example">msgattrib [<var>option</var>] [<var>inputfile</var>] | |
| 1914 </pre></td></tr></table> | |
| 1915 | |
| 1916 <a name="IDX769"></a> | |
| 1917 <a name="IDX770"></a> | |
| 1918 <p>The <code>msgattrib</code> program filters the messages of a translation catalog | |
| 1919 according to their attributes, and manipulates the attributes. | |
| 1920 </p> | |
| 1921 | |
| 1922 <a name="SEC140"></a> | |
| 1923 <h3 class="subsection"> <a href="gettext_toc.html#TOC133">9.8.1 Input file location</a> </h3> | |
| 1924 | |
| 1925 <dl compact="compact"> | |
| 1926 <dt> ‘<samp><var>inputfile</var></samp>’</dt> | |
| 1927 <dd><p>Input PO file. | |
| 1928 </p> | |
| 1929 </dd> | |
| 1930 <dt> ‘<samp>-D <var>directory</var></samp>’</dt> | |
| 1931 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt> | |
| 1932 <dd><a name="IDX771"></a> | |
| 1933 <a name="IDX772"></a> | |
| 1934 <p>Add <var>directory</var> to the list of directories. Source files are | |
| 1935 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’ | |
| 1936 file will be written relative to the current directory, though. | |
| 1937 </p> | |
| 1938 </dd> | |
| 1939 </dl> | |
| 1940 | |
| 1941 <p>If no <var>inputfile</var> is given or if it is ‘<samp>-</samp>’, standard input is read. | |
| 1942 </p> | |
| 1943 | |
| 1944 <a name="SEC141"></a> | |
| 1945 <h3 class="subsection"> <a href="gettext_toc.html#TOC134">9.8.2 Output file location</a> </h3> | |
| 1946 | |
| 1947 <dl compact="compact"> | |
| 1948 <dt> ‘<samp>-o <var>file</var></samp>’</dt> | |
| 1949 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt> | |
| 1950 <dd><a name="IDX773"></a> | |
| 1951 <a name="IDX774"></a> | |
| 1952 <p>Write output to specified file. | |
| 1953 </p> | |
| 1954 </dd> | |
| 1955 </dl> | |
| 1956 | |
| 1957 <p>The results are written to standard output if no output file is specified | |
| 1958 or if it is ‘<samp>-</samp>’. | |
| 1959 </p> | |
| 1960 | |
| 1961 <a name="SEC142"></a> | |
| 1962 <h3 class="subsection"> <a href="gettext_toc.html#TOC135">9.8.3 Message selection</a> </h3> | |
| 1963 | |
| 1964 <dl compact="compact"> | |
| 1965 <dt> ‘<samp>--translated</samp>’</dt> | |
| 1966 <dd><a name="IDX775"></a> | |
| 1967 <p>Keep translated messages, remove untranslated messages. | |
| 1968 </p> | |
| 1969 </dd> | |
| 1970 <dt> ‘<samp>--untranslated</samp>’</dt> | |
| 1971 <dd><a name="IDX776"></a> | |
| 1972 <p>Keep untranslated messages, remove translated messages. | |
| 1973 </p> | |
| 1974 </dd> | |
| 1975 <dt> ‘<samp>--no-fuzzy</samp>’</dt> | |
| 1976 <dd><a name="IDX777"></a> | |
| 1977 <p>Remove | |
| 1978 ‘fuzzy’ | |
| 1979 marked messages. | |
| 1980 </p> | |
| 1981 </dd> | |
| 1982 <dt> ‘<samp>--only-fuzzy</samp>’</dt> | |
| 1983 <dd><a name="IDX778"></a> | |
| 1984 <p>Keep | |
| 1985 ‘fuzzy’ | |
| 1986 marked messages, remove all other messages. | |
| 1987 </p> | |
| 1988 </dd> | |
| 1989 <dt> ‘<samp>--no-obsolete</samp>’</dt> | |
| 1990 <dd><a name="IDX779"></a> | |
| 1991 <p>Remove obsolete #~ messages. | |
| 1992 </p> | |
| 1993 </dd> | |
| 1994 <dt> ‘<samp>--only-obsolete</samp>’</dt> | |
| 1995 <dd><a name="IDX780"></a> | |
| 1996 <p>Keep obsolete #~ messages, remove all other messages. | |
| 1997 </p> | |
| 1998 </dd> | |
| 1999 </dl> | |
| 2000 | |
| 2001 | |
| 2002 <a name="SEC143"></a> | |
| 2003 <h3 class="subsection"> <a href="gettext_toc.html#TOC136">9.8.4 Attribute manipulation</a> </h3> | |
| 2004 | |
| 2005 <p>Attributes are modified after the message selection/removal has been | |
| 2006 performed. If the ‘<samp>--only-file</samp>’ or ‘<samp>--ignore-file</samp>’ option is | |
| 2007 specified, the attribute modification is applied only to those messages | |
| 2008 that are listed in the <var>only-file</var> and not listed in the | |
| 2009 <var>ignore-file</var>. | |
| 2010 </p> | |
| 2011 <dl compact="compact"> | |
| 2012 <dt> ‘<samp>--set-fuzzy</samp>’</dt> | |
| 2013 <dd><a name="IDX781"></a> | |
| 2014 <p>Set all messages | |
| 2015 ‘fuzzy’. | |
| 2016 </p> | |
| 2017 </dd> | |
| 2018 <dt> ‘<samp>--clear-fuzzy</samp>’</dt> | |
| 2019 <dd><a name="IDX782"></a> | |
| 2020 <p>Set all messages | |
| 2021 non-‘fuzzy’. | |
| 2022 </p> | |
| 2023 </dd> | |
| 2024 <dt> ‘<samp>--set-obsolete</samp>’</dt> | |
| 2025 <dd><a name="IDX783"></a> | |
| 2026 <p>Set all messages obsolete. | |
| 2027 </p> | |
| 2028 </dd> | |
| 2029 <dt> ‘<samp>--clear-obsolete</samp>’</dt> | |
| 2030 <dd><a name="IDX784"></a> | |
| 2031 <p>Set all messages non-obsolete. | |
| 2032 </p> | |
| 2033 </dd> | |
| 2034 <dt> ‘<samp>--previous</samp>’</dt> | |
| 2035 <dd><a name="IDX785"></a> | |
| 2036 <p>When setting | |
| 2037 ‘fuzzy’ | |
| 2038 mark, keep “previous msgid” of translated messages. | |
| 2039 </p> | |
| 2040 </dd> | |
| 2041 <dt> ‘<samp>--clear-previous</samp>’</dt> | |
| 2042 <dd><a name="IDX786"></a> | |
| 2043 <p>Remove the “previous msgid” (‘<samp>#|</samp>’) comments from all messages. | |
| 2044 </p> | |
| 2045 </dd> | |
| 2046 <dt> ‘<samp>--empty</samp>’</dt> | |
| 2047 <dd><a name="IDX787"></a> | |
| 2048 <p>When removing | |
| 2049 ‘fuzzy’ | |
| 2050 mark, also set msgstr empty. | |
| 2051 </p> | |
| 2052 </dd> | |
| 2053 <dt> ‘<samp>--only-file=<var>file</var></samp>’</dt> | |
| 2054 <dd><a name="IDX788"></a> | |
| 2055 <p>Limit the attribute changes to entries that are listed in <var>file</var>. | |
| 2056 <var>file</var> should be a PO or POT file. | |
| 2057 </p> | |
| 2058 </dd> | |
| 2059 <dt> ‘<samp>--ignore-file=<var>file</var></samp>’</dt> | |
| 2060 <dd><a name="IDX789"></a> | |
| 2061 <p>Limit the attribute changes to entries that are not listed in <var>file</var>. | |
| 2062 <var>file</var> should be a PO or POT file. | |
| 2063 </p> | |
| 2064 </dd> | |
| 2065 <dt> ‘<samp>--fuzzy</samp>’</dt> | |
| 2066 <dd><a name="IDX790"></a> | |
| 2067 <p>Synonym for ‘<samp>--only-fuzzy --clear-fuzzy</samp>’: It keeps only the fuzzy | |
| 2068 messages and removes their | |
| 2069 ‘fuzzy’ | |
| 2070 mark. | |
| 2071 </p> | |
| 2072 </dd> | |
| 2073 <dt> ‘<samp>--obsolete</samp>’</dt> | |
| 2074 <dd><a name="IDX791"></a> | |
| 2075 <p>Synonym for ‘<samp>--only-obsolete --clear-obsolete</samp>’: It keeps only the | |
| 2076 obsolete messages and makes them non-obsolete. | |
| 2077 </p> | |
| 2078 </dd> | |
| 2079 </dl> | |
| 2080 | |
| 2081 | |
| 2082 <a name="SEC144"></a> | |
| 2083 <h3 class="subsection"> <a href="gettext_toc.html#TOC137">9.8.5 Input file syntax</a> </h3> | |
| 2084 | |
| 2085 <dl compact="compact"> | |
| 2086 <dt> ‘<samp>-P</samp>’</dt> | |
| 2087 <dt> ‘<samp>--properties-input</samp>’</dt> | |
| 2088 <dd><a name="IDX792"></a> | |
| 2089 <a name="IDX793"></a> | |
| 2090 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> | |
| 2091 syntax, not in PO file syntax. | |
| 2092 </p> | |
| 2093 </dd> | |
| 2094 <dt> ‘<samp>--stringtable-input</samp>’</dt> | |
| 2095 <dd><a name="IDX794"></a> | |
| 2096 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in | |
| 2097 <code>.strings</code> syntax, not in PO file syntax. | |
| 2098 </p> | |
| 2099 </dd> | |
| 2100 </dl> | |
| 2101 | |
| 2102 | |
| 2103 <a name="SEC145"></a> | |
| 2104 <h3 class="subsection"> <a href="gettext_toc.html#TOC138">9.8.6 Output details</a> </h3> | |
| 2105 | |
| 2106 | |
| 2107 <dl compact="compact"> | |
| 2108 <dt> ‘<samp>--color</samp>’</dt> | |
| 2109 <dt> ‘<samp>--color=<var>when</var></samp>’</dt> | |
| 2110 <dd><a name="IDX795"></a> | |
| 2111 <p>Specify whether or when to use colors and other text attributes. | |
| 2112 See <a href="#SEC158">The <code>--color</code> option</a> for details. | |
| 2113 </p> | |
| 2114 </dd> | |
| 2115 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt> | |
| 2116 <dd><a name="IDX796"></a> | |
| 2117 <p>Specify the CSS style rule file to use for <code>--color</code>. | |
| 2118 See <a href="#SEC160">The <code>--style</code> option</a> for details. | |
| 2119 </p> | |
| 2120 </dd> | |
| 2121 <dt> ‘<samp>--force-po</samp>’</dt> | |
| 2122 <dd><a name="IDX797"></a> | |
| 2123 <p>Always write an output file even if it contains no message. | |
| 2124 </p> | |
| 2125 </dd> | |
| 2126 <dt> ‘<samp>-i</samp>’</dt> | |
| 2127 <dt> ‘<samp>--indent</samp>’</dt> | |
| 2128 <dd><a name="IDX798"></a> | |
| 2129 <a name="IDX799"></a> | |
| 2130 <p>Write the .po file using indented style. | |
| 2131 </p> | |
| 2132 </dd> | |
| 2133 <dt> ‘<samp>--no-location</samp>’</dt> | |
| 2134 <dd><a name="IDX800"></a> | |
| 2135 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines. | |
| 2136 </p> | |
| 2137 </dd> | |
| 2138 <dt> ‘<samp>-n</samp>’</dt> | |
| 2139 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt> | |
| 2140 <dd><a name="IDX801"></a> | |
| 2141 <a name="IDX802"></a> | |
| 2142 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default). | |
| 2143 </p> | |
| 2144 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or | |
| 2145 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the | |
| 2146 lines with both file name and line number. If it is ‘<samp>file</samp>’, the | |
| 2147 line number part is omitted. If it is ‘<samp>never</samp>’, it completely | |
| 2148 suppresses the lines (same as <code>--no-location</code>). | |
| 2149 </p> | |
| 2150 </dd> | |
| 2151 <dt> ‘<samp>--strict</samp>’</dt> | |
| 2152 <dd><a name="IDX803"></a> | |
| 2153 <p>Write out a strict Uniforum conforming PO file. Note that this | |
| 2154 Uniforum format should be avoided because it doesn't support the | |
| 2155 GNU extensions. | |
| 2156 </p> | |
| 2157 </dd> | |
| 2158 <dt> ‘<samp>-p</samp>’</dt> | |
| 2159 <dt> ‘<samp>--properties-output</samp>’</dt> | |
| 2160 <dd><a name="IDX804"></a> | |
| 2161 <a name="IDX805"></a> | |
| 2162 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note | |
| 2163 that this file format doesn't support plural forms and silently drops | |
| 2164 obsolete messages. | |
| 2165 </p> | |
| 2166 </dd> | |
| 2167 <dt> ‘<samp>--stringtable-output</samp>’</dt> | |
| 2168 <dd><a name="IDX806"></a> | |
| 2169 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. | |
| 2170 Note that this file format doesn't support plural forms. | |
| 2171 </p> | |
| 2172 </dd> | |
| 2173 <dt> ‘<samp>-w <var>number</var></samp>’</dt> | |
| 2174 <dt> ‘<samp>--width=<var>number</var></samp>’</dt> | |
| 2175 <dd><a name="IDX807"></a> | |
| 2176 <a name="IDX808"></a> | |
| 2177 <p>Set the output page width. Long strings in the output files will be | |
| 2178 split across multiple lines in order to ensure that each line's width | |
| 2179 (= number of screen columns) is less or equal to the given <var>number</var>. | |
| 2180 </p> | |
| 2181 </dd> | |
| 2182 <dt> ‘<samp>--no-wrap</samp>’</dt> | |
| 2183 <dd><a name="IDX809"></a> | |
| 2184 <p>Do not break long message lines. Message lines whose width exceeds the | |
| 2185 output page width will not be split into several lines. Only file reference | |
| 2186 lines which are wider than the output page width will be split. | |
| 2187 </p> | |
| 2188 </dd> | |
| 2189 <dt> ‘<samp>-s</samp>’</dt> | |
| 2190 <dt> ‘<samp>--sort-output</samp>’</dt> | |
| 2191 <dd><a name="IDX810"></a> | |
| 2192 <a name="IDX811"></a> | |
| 2193 <p>Generate sorted output. Note that using this option makes it much harder | |
| 2194 for the translator to understand each message's context. | |
| 2195 </p> | |
| 2196 </dd> | |
| 2197 <dt> ‘<samp>-F</samp>’</dt> | |
| 2198 <dt> ‘<samp>--sort-by-file</samp>’</dt> | |
| 2199 <dd><a name="IDX812"></a> | |
| 2200 <a name="IDX813"></a> | |
| 2201 <p>Sort output by file location. | |
| 2202 </p> | |
| 2203 </dd> | |
| 2204 </dl> | |
| 2205 | |
| 2206 | |
| 2207 <a name="SEC146"></a> | |
| 2208 <h3 class="subsection"> <a href="gettext_toc.html#TOC139">9.8.7 Informative output</a> </h3> | |
| 2209 | |
| 2210 <dl compact="compact"> | |
| 2211 <dt> ‘<samp>-h</samp>’</dt> | |
| 2212 <dt> ‘<samp>--help</samp>’</dt> | |
| 2213 <dd><a name="IDX814"></a> | |
| 2214 <a name="IDX815"></a> | |
| 2215 <p>Display this help and exit. | |
| 2216 </p> | |
| 2217 </dd> | |
| 2218 <dt> ‘<samp>-V</samp>’</dt> | |
| 2219 <dt> ‘<samp>--version</samp>’</dt> | |
| 2220 <dd><a name="IDX816"></a> | |
| 2221 <a name="IDX817"></a> | |
| 2222 <p>Output version information and exit. | |
| 2223 </p> | |
| 2224 </dd> | |
| 2225 </dl> | |
| 2226 | |
| 2227 | |
| 2228 <a name="msgen-Invocation"></a> | |
| 2229 <a name="SEC147"></a> | |
| 2230 <h2 class="section"> <a href="gettext_toc.html#TOC140">9.9 Invoking the <code>msgen</code> Program</a> </h2> | |
| 2231 | |
| 2232 | |
| 2233 <table><tr><td> </td><td><pre class="example">msgen [<var>option</var>] <var>inputfile</var> | |
| 2234 </pre></td></tr></table> | |
| 2235 | |
| 2236 <a name="IDX818"></a> | |
| 2237 <p>The <code>msgen</code> program creates an English translation catalog. The | |
| 2238 input file is the last created English PO file, or a PO Template file | |
| 2239 (generally created by xgettext). Untranslated entries are assigned a | |
| 2240 translation that is identical to the msgid. | |
| 2241 </p> | |
| 2242 <p>Note: ‘<samp>msginit --no-translator --locale=en</samp>’ performs a very similar | |
| 2243 task. The main difference is that <code>msginit</code> cares specially about | |
| 2244 the header entry, whereas <code>msgen</code> doesn't. | |
| 2245 </p> | |
| 2246 | |
| 2247 <a name="SEC148"></a> | |
| 2248 <h3 class="subsection"> <a href="gettext_toc.html#TOC141">9.9.1 Input file location</a> </h3> | |
| 2249 | |
| 2250 <dl compact="compact"> | |
| 2251 <dt> ‘<samp><var>inputfile</var></samp>’</dt> | |
| 2252 <dd><p>Input PO or POT file. | |
| 2253 </p> | |
| 2254 </dd> | |
| 2255 <dt> ‘<samp>-D <var>directory</var></samp>’</dt> | |
| 2256 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt> | |
| 2257 <dd><a name="IDX819"></a> | |
| 2258 <a name="IDX820"></a> | |
| 2259 <p>Add <var>directory</var> to the list of directories. Source files are | |
| 2260 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’ | |
| 2261 file will be written relative to the current directory, though. | |
| 2262 </p> | |
| 2263 </dd> | |
| 2264 </dl> | |
| 2265 | |
| 2266 <p>If <var>inputfile</var> is ‘<samp>-</samp>’, standard input is read. | |
| 2267 </p> | |
| 2268 | |
| 2269 <a name="SEC149"></a> | |
| 2270 <h3 class="subsection"> <a href="gettext_toc.html#TOC142">9.9.2 Output file location</a> </h3> | |
| 2271 | |
| 2272 <dl compact="compact"> | |
| 2273 <dt> ‘<samp>-o <var>file</var></samp>’</dt> | |
| 2274 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt> | |
| 2275 <dd><a name="IDX821"></a> | |
| 2276 <a name="IDX822"></a> | |
| 2277 <p>Write output to specified file. | |
| 2278 </p> | |
| 2279 </dd> | |
| 2280 </dl> | |
| 2281 | |
| 2282 <p>The results are written to standard output if no output file is specified | |
| 2283 or if it is ‘<samp>-</samp>’. | |
| 2284 </p> | |
| 2285 | |
| 2286 <a name="SEC150"></a> | |
| 2287 <h3 class="subsection"> <a href="gettext_toc.html#TOC143">9.9.3 Input file syntax</a> </h3> | |
| 2288 | |
| 2289 <dl compact="compact"> | |
| 2290 <dt> ‘<samp>-P</samp>’</dt> | |
| 2291 <dt> ‘<samp>--properties-input</samp>’</dt> | |
| 2292 <dd><a name="IDX823"></a> | |
| 2293 <a name="IDX824"></a> | |
| 2294 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> | |
| 2295 syntax, not in PO file syntax. | |
| 2296 </p> | |
| 2297 </dd> | |
| 2298 <dt> ‘<samp>--stringtable-input</samp>’</dt> | |
| 2299 <dd><a name="IDX825"></a> | |
| 2300 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in | |
| 2301 <code>.strings</code> syntax, not in PO file syntax. | |
| 2302 </p> | |
| 2303 </dd> | |
| 2304 </dl> | |
| 2305 | |
| 2306 | |
| 2307 <a name="SEC151"></a> | |
| 2308 <h3 class="subsection"> <a href="gettext_toc.html#TOC144">9.9.4 Output details</a> </h3> | |
| 2309 | |
| 2310 | |
| 2311 <dl compact="compact"> | |
| 2312 <dt> ‘<samp>--lang=<var>catalogname</var></samp>’</dt> | |
| 2313 <dd><a name="IDX826"></a> | |
| 2314 <p>Specify the ‘<samp>Language</samp>’ field to be used in the header entry. See | |
| 2315 <a href="gettext_6.html#SEC52">Filling in the Header Entry</a> for the meaning of this field. Note: The | |
| 2316 ‘<samp>Language-Team</samp>’ and ‘<samp>Plural-Forms</samp>’ fields are not set by this | |
| 2317 option. | |
| 2318 </p> | |
| 2319 </dd> | |
| 2320 <dt> ‘<samp>--color</samp>’</dt> | |
| 2321 <dt> ‘<samp>--color=<var>when</var></samp>’</dt> | |
| 2322 <dd><a name="IDX827"></a> | |
| 2323 <p>Specify whether or when to use colors and other text attributes. | |
| 2324 See <a href="#SEC158">The <code>--color</code> option</a> for details. | |
| 2325 </p> | |
| 2326 </dd> | |
| 2327 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt> | |
| 2328 <dd><a name="IDX828"></a> | |
| 2329 <p>Specify the CSS style rule file to use for <code>--color</code>. | |
| 2330 See <a href="#SEC160">The <code>--style</code> option</a> for details. | |
| 2331 </p> | |
| 2332 </dd> | |
| 2333 <dt> ‘<samp>--force-po</samp>’</dt> | |
| 2334 <dd><a name="IDX829"></a> | |
| 2335 <p>Always write an output file even if it contains no message. | |
| 2336 </p> | |
| 2337 </dd> | |
| 2338 <dt> ‘<samp>-i</samp>’</dt> | |
| 2339 <dt> ‘<samp>--indent</samp>’</dt> | |
| 2340 <dd><a name="IDX830"></a> | |
| 2341 <a name="IDX831"></a> | |
| 2342 <p>Write the .po file using indented style. | |
| 2343 </p> | |
| 2344 </dd> | |
| 2345 <dt> ‘<samp>--no-location</samp>’</dt> | |
| 2346 <dd><a name="IDX832"></a> | |
| 2347 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines. | |
| 2348 </p> | |
| 2349 </dd> | |
| 2350 <dt> ‘<samp>-n</samp>’</dt> | |
| 2351 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt> | |
| 2352 <dd><a name="IDX833"></a> | |
| 2353 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default). | |
| 2354 </p> | |
| 2355 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or | |
| 2356 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the | |
| 2357 lines with both file name and line number. If it is ‘<samp>file</samp>’, the | |
| 2358 line number part is omitted. If it is ‘<samp>never</samp>’, it completely | |
| 2359 suppresses the lines (same as <code>--no-location</code>). | |
| 2360 </p> | |
| 2361 </dd> | |
| 2362 <dt> ‘<samp>--strict</samp>’</dt> | |
| 2363 <dd><a name="IDX834"></a> | |
| 2364 <p>Write out a strict Uniforum conforming PO file. Note that this | |
| 2365 Uniforum format should be avoided because it doesn't support the | |
| 2366 GNU extensions. | |
| 2367 </p> | |
| 2368 </dd> | |
| 2369 <dt> ‘<samp>-p</samp>’</dt> | |
| 2370 <dt> ‘<samp>--properties-output</samp>’</dt> | |
| 2371 <dd><a name="IDX835"></a> | |
| 2372 <a name="IDX836"></a> | |
| 2373 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note | |
| 2374 that this file format doesn't support plural forms and silently drops | |
| 2375 obsolete messages. | |
| 2376 </p> | |
| 2377 </dd> | |
| 2378 <dt> ‘<samp>--stringtable-output</samp>’</dt> | |
| 2379 <dd><a name="IDX837"></a> | |
| 2380 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax. | |
| 2381 Note that this file format doesn't support plural forms. | |
| 2382 </p> | |
| 2383 </dd> | |
| 2384 <dt> ‘<samp>-w <var>number</var></samp>’</dt> | |
| 2385 <dt> ‘<samp>--width=<var>number</var></samp>’</dt> | |
| 2386 <dd><a name="IDX838"></a> | |
| 2387 <a name="IDX839"></a> | |
| 2388 <p>Set the output page width. Long strings in the output files will be | |
| 2389 split across multiple lines in order to ensure that each line's width | |
| 2390 (= number of screen columns) is less or equal to the given <var>number</var>. | |
| 2391 </p> | |
| 2392 </dd> | |
| 2393 <dt> ‘<samp>--no-wrap</samp>’</dt> | |
| 2394 <dd><a name="IDX840"></a> | |
| 2395 <p>Do not break long message lines. Message lines whose width exceeds the | |
| 2396 output page width will not be split into several lines. Only file reference | |
| 2397 lines which are wider than the output page width will be split. | |
| 2398 </p> | |
| 2399 </dd> | |
| 2400 <dt> ‘<samp>-s</samp>’</dt> | |
| 2401 <dt> ‘<samp>--sort-output</samp>’</dt> | |
| 2402 <dd><a name="IDX841"></a> | |
| 2403 <a name="IDX842"></a> | |
| 2404 <p>Generate sorted output. Note that using this option makes it much harder | |
| 2405 for the translator to understand each message's context. | |
| 2406 </p> | |
| 2407 </dd> | |
| 2408 <dt> ‘<samp>-F</samp>’</dt> | |
| 2409 <dt> ‘<samp>--sort-by-file</samp>’</dt> | |
| 2410 <dd><a name="IDX843"></a> | |
| 2411 <a name="IDX844"></a> | |
| 2412 <p>Sort output by file location. | |
| 2413 </p> | |
| 2414 </dd> | |
| 2415 </dl> | |
| 2416 | |
| 2417 | |
| 2418 <a name="SEC152"></a> | |
| 2419 <h3 class="subsection"> <a href="gettext_toc.html#TOC145">9.9.5 Informative output</a> </h3> | |
| 2420 | |
| 2421 <dl compact="compact"> | |
| 2422 <dt> ‘<samp>-h</samp>’</dt> | |
| 2423 <dt> ‘<samp>--help</samp>’</dt> | |
| 2424 <dd><a name="IDX845"></a> | |
| 2425 <a name="IDX846"></a> | |
| 2426 <p>Display this help and exit. | |
| 2427 </p> | |
| 2428 </dd> | |
| 2429 <dt> ‘<samp>-V</samp>’</dt> | |
| 2430 <dt> ‘<samp>--version</samp>’</dt> | |
| 2431 <dd><a name="IDX847"></a> | |
| 2432 <a name="IDX848"></a> | |
| 2433 <p>Output version information and exit. | |
| 2434 </p> | |
| 2435 </dd> | |
| 2436 </dl> | |
| 2437 | |
| 2438 | |
| 2439 <a name="msgexec-Invocation"></a> | |
| 2440 <a name="SEC153"></a> | |
| 2441 <h2 class="section"> <a href="gettext_toc.html#TOC146">9.10 Invoking the <code>msgexec</code> Program</a> </h2> | |
| 2442 | |
| 2443 | |
| 2444 <table><tr><td> </td><td><pre class="example">msgexec [<var>option</var>] <var>command</var> [<var>command-option</var>] | |
| 2445 </pre></td></tr></table> | |
| 2446 | |
| 2447 <a name="IDX849"></a> | |
| 2448 <p>The <code>msgexec</code> program applies a command to all translations of a | |
| 2449 translation catalog. | |
| 2450 The <var>command</var> can be any program that reads a translation from standard | |
| 2451 input. It is invoked once for each translation. Its output becomes | |
| 2452 msgexec's output. <code>msgexec</code>'s return code is the maximum return code | |
| 2453 across all invocations. | |
| 2454 </p> | |
| 2455 <a name="IDX850"></a> | |
| 2456 <p>A special builtin command called ‘<samp>0</samp>’ outputs the translation, followed | |
| 2457 by a null byte. The output of ‘<samp>msgexec 0</samp>’ is suitable as input for | |
| 2458 ‘<samp>xargs -0</samp>’. | |
| 2459 </p> | |
| 2460 <dl compact="compact"> | |
| 2461 <dt> ‘<samp>--newline</samp>’</dt> | |
| 2462 <dd><a name="IDX851"></a> | |
| 2463 <p>Add newline at the end of each input line. | |
| 2464 </p> | |
| 2465 </dd> | |
| 2466 </dl> | |
| 2467 | |
| 2468 <a name="IDX852"></a> | |
| 2469 <a name="IDX853"></a> | |
| 2470 <a name="IDX854"></a> | |
| 2471 <a name="IDX855"></a> | |
| 2472 <a name="IDX856"></a> | |
| 2473 <a name="IDX857"></a> | |
| 2474 <a name="IDX858"></a> | |
| 2475 <a name="IDX859"></a> | |
| 2476 <p>During each <var>command</var> invocation, the environment variable | |
| 2477 <code>MSGEXEC_MSGID</code> is bound to the message's msgid, and the environment | |
| 2478 variable <code>MSGEXEC_LOCATION</code> is bound to the location in the PO file | |
| 2479 of the message. If the message has a context, the environment variable | |
| 2480 <code>MSGEXEC_MSGCTXT</code> is bound to the message's msgctxt, otherwise it is | |
| 2481 unbound. If the message has a plural form, environment variable | |
| 2482 <code>MSGEXEC_MSGID_PLURAL</code> is bound to the message's msgid_plural and | |
| 2483 <code>MSGEXEC_PLURAL_FORM</code> is bound to the order number of the plural | |
| 2484 actually processed (starting with 0), otherwise both are unbound. | |
| 2485 If the message has a previous msgid (added by <code>msgmerge</code>), | |
| 2486 environment variable <code>MSGEXEC_PREV_MSGCTXT</code> is bound to the | |
| 2487 message's previous msgctxt, <code>MSGEXEC_PREV_MSGID</code> is bound to | |
| 2488 the previous msgid, and <code>MSGEXEC_PREV_MSGID_PLURAL</code> is bound to | |
| 2489 the previous msgid_plural. | |
| 2490 </p> | |
| 2491 <a name="IDX860"></a> | |
| 2492 <p>Note: It is your responsibility to ensure that the <var>command</var> can cope | |
| 2493 with input encoded in the translation catalog's encoding. If the | |
| 2494 <var>command</var> wants input in a particular encoding, you can in a first step | |
| 2495 convert the translation catalog to that encoding using the ‘<samp>msgconv</samp>’ | |
| 2496 program, before invoking ‘<samp>msgexec</samp>’. If the <var>command</var> wants input | |
| 2497 in the locale's encoding, but you want to avoid the locale's encoding, then | |
| 2498 you can first convert the translation catalog to UTF-8 using the | |
| 2499 ‘<samp>msgconv</samp>’ program and then make ‘<samp>msgexec</samp>’ work in an UTF-8 | |
| 2500 locale, by using the <code>LC_ALL</code> environment variable. | |
| 2501 </p> | |
| 2502 | |
| 2503 <a name="SEC154"></a> | |
| 2504 <h3 class="subsection"> <a href="gettext_toc.html#TOC147">9.10.1 Input file location</a> </h3> | |
| 2505 | |
| 2506 <dl compact="compact"> | |
| 2507 <dt> ‘<samp>-i <var>inputfile</var></samp>’</dt> | |
| 2508 <dt> ‘<samp>--input=<var>inputfile</var></samp>’</dt> | |
| 2509 <dd><a name="IDX861"></a> | |
| 2510 <a name="IDX862"></a> | |
| 2511 <p>Input PO file. | |
| 2512 </p> | |
| 2513 </dd> | |
| 2514 <dt> ‘<samp>-D <var>directory</var></samp>’</dt> | |
| 2515 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt> | |
| 2516 <dd><a name="IDX863"></a> | |
| 2517 <a name="IDX864"></a> | |
| 2518 <p>Add <var>directory</var> to the list of directories. Source files are | |
| 2519 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’ | |
| 2520 file will be written relative to the current directory, though. | |
| 2521 </p> | |
| 2522 </dd> | |
| 2523 </dl> | |
| 2524 | |
| 2525 <p>If no <var>inputfile</var> is given or if it is ‘<samp>-</samp>’, standard input is read. | |
| 2526 </p> | |
| 2527 | |
| 2528 <a name="SEC155"></a> | |
| 2529 <h3 class="subsection"> <a href="gettext_toc.html#TOC148">9.10.2 Input file syntax</a> </h3> | |
| 2530 | |
| 2531 <dl compact="compact"> | |
| 2532 <dt> ‘<samp>-P</samp>’</dt> | |
| 2533 <dt> ‘<samp>--properties-input</samp>’</dt> | |
| 2534 <dd><a name="IDX865"></a> | |
| 2535 <a name="IDX866"></a> | |
| 2536 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code> | |
| 2537 syntax, not in PO file syntax. | |
| 2538 </p> | |
| 2539 </dd> | |
| 2540 <dt> ‘<samp>--stringtable-input</samp>’</dt> | |
| 2541 <dd><a name="IDX867"></a> | |
| 2542 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in | |
| 2543 <code>.strings</code> syntax, not in PO file syntax. | |
| 2544 </p> | |
| 2545 </dd> | |
| 2546 </dl> | |
| 2547 | |
| 2548 | |
| 2549 <a name="SEC156"></a> | |
| 2550 <h3 class="subsection"> <a href="gettext_toc.html#TOC149">9.10.3 Informative output</a> </h3> | |
| 2551 | |
| 2552 <dl compact="compact"> | |
| 2553 <dt> ‘<samp>-h</samp>’</dt> | |
| 2554 <dt> ‘<samp>--help</samp>’</dt> | |
| 2555 <dd><a name="IDX868"></a> | |
| 2556 <a name="IDX869"></a> | |
| 2557 <p>Display this help and exit. | |
| 2558 </p> | |
| 2559 </dd> | |
| 2560 <dt> ‘<samp>-V</samp>’</dt> | |
| 2561 <dt> ‘<samp>--version</samp>’</dt> | |
| 2562 <dd><a name="IDX870"></a> | |
| 2563 <a name="IDX871"></a> | |
| 2564 <p>Output version information and exit. | |
| 2565 </p> | |
| 2566 </dd> | |
| 2567 </dl> | |
| 2568 | |
| 2569 | |
| 2570 <a name="Colorizing"></a> | |
| 2571 <a name="SEC157"></a> | |
| 2572 <h2 class="section"> <a href="gettext_toc.html#TOC150">9.11 Highlighting parts of PO files</a> </h2> | |
| 2573 | |
| 2574 <p>Translators are usually only interested in seeing the untranslated and | |
| 2575 fuzzy messages of a PO file. Also, when a message is set fuzzy because | |
| 2576 the msgid changed, they want to see the differences between the previous | |
| 2577 msgid and the current one (especially if the msgid is long and only few | |
| 2578 words in it have changed). Finally, it's always welcome to highlight the | |
| 2579 different sections of a message in a PO file (comments, msgid, msgstr, etc.). | |
| 2580 </p> | |
| 2581 <p>Such highlighting is possible through the options ‘<samp>--color</samp>’ and | |
| 2582 ‘<samp>--style</samp>’. They are supported by all the programs that produce | |
| 2583 a PO file on standard output, such as <code>msgcat</code>, <code>msgmerge</code>, | |
| 2584 and <code>msgunfmt</code>. | |
| 2585 </p> | |
| 2586 | |
| 2587 | |
| 2588 <a name="The-_002d_002dcolor-option"></a> | |
| 2589 <a name="SEC158"></a> | |
| 2590 <h3 class="subsection"> <a href="gettext_toc.html#TOC151">9.11.1 The <code>--color</code> option</a> </h3> | |
| 2591 | |
| 2592 <p>The ‘<samp>--color=<var>when</var></samp>’ option specifies under which conditions | |
| 2593 colorized output should be generated. The <var>when</var> part can be one of | |
| 2594 the following: | |
| 2595 </p> | |
| 2596 <dl compact="compact"> | |
| 2597 <dt> <code>always</code></dt> | |
| 2598 <dt> <code>yes</code></dt> | |
| 2599 <dd><p>The output will be colorized. | |
| 2600 </p> | |
| 2601 </dd> | |
| 2602 <dt> <code>never</code></dt> | |
| 2603 <dt> <code>no</code></dt> | |
| 2604 <dd><p>The output will not be colorized. | |
| 2605 </p> | |
| 2606 </dd> | |
| 2607 <dt> <code>auto</code></dt> | |
| 2608 <dt> <code>tty</code></dt> | |
| 2609 <dd><p>The output will be colorized if the output device is a tty, i.e. when the | |
| 2610 output goes directly to a text screen or terminal emulator window. | |
| 2611 </p> | |
| 2612 </dd> | |
| 2613 <dt> <code>html</code></dt> | |
| 2614 <dd><p>The output will be colorized and be in HTML format. | |
| 2615 </p> | |
| 2616 </dd> | |
| 2617 <dt> <code>test</code></dt> | |
| 2618 <dd><p>This is a special value, understood only by the <code>msgcat</code> program. It | |
| 2619 is explained in the next section (<a href="#SEC159">The environment variable <code>TERM</code></a>). | |
| 2620 </p></dd> | |
| 2621 </dl> | |
| 2622 | |
| 2623 <p>‘<samp>--color</samp>’ is equivalent to ‘<samp>--color=yes</samp>’. The default is | |
| 2624 ‘<samp>--color=auto</samp>’. | |
| 2625 </p> | |
| 2626 <p>Thus, a command like ‘<samp>msgcat vi.po</samp>’ will produce colorized output | |
| 2627 when called by itself in a command window. Whereas in a pipe, such as | |
| 2628 ‘<samp>msgcat vi.po | less -R</samp>’, it will not produce colorized output. To | |
| 2629 get colorized output in this situation nevertheless, use the command | |
| 2630 ‘<samp>msgcat --color vi.po | less -R</samp>’. | |
| 2631 </p> | |
| 2632 <p>The ‘<samp>--color=html</samp>’ option will produce output that can be viewed in | |
| 2633 a browser. This can be useful, for example, for Indic languages, | |
| 2634 because the renderic of Indic scripts in browsers is usually better than | |
| 2635 in terminal emulators. | |
| 2636 </p> | |
| 2637 <p>Note that the output produced with the <code>--color</code> option is <em>not</em> | |
| 2638 a valid PO file in itself. It contains additional terminal-specific escape | |
| 2639 sequences or HTML tags. A PO file reader will give a syntax error when | |
| 2640 confronted with such content. Except for the ‘<samp>--color=html</samp>’ case, | |
| 2641 you therefore normally don't need to save output produced with the | |
| 2642 <code>--color</code> option in a file. | |
| 2643 </p> | |
| 2644 | |
| 2645 <a name="The-TERM-variable"></a> | |
| 2646 <a name="SEC159"></a> | |
| 2647 <h3 class="subsection"> <a href="gettext_toc.html#TOC152">9.11.2 The environment variable <code>TERM</code></a> </h3> | |
| 2648 | |
| 2649 <p>The environment variable <code>TERM</code> contains a identifier for the text | |
| 2650 window's capabilities. You can get a detailed list of these cababilities | |
| 2651 by using the ‘<samp>infocmp</samp>’ command, using ‘<samp>man 5 terminfo</samp>’ as a | |
| 2652 reference. | |
| 2653 </p> | |
| 2654 <p>When producing text with embedded color directives, <code>msgcat</code> looks | |
| 2655 at the <code>TERM</code> variable. Text windows today typically support at least | |
| 2656 8 colors. Often, however, the text window supports 16 or more colors, | |
| 2657 even though the <code>TERM</code> variable is set to a identifier denoting only | |
| 2658 8 supported colors. It can be worth setting the <code>TERM</code> variable to | |
| 2659 a different value in these cases: | |
| 2660 </p> | |
| 2661 <dl compact="compact"> | |
| 2662 <dt> <code>xterm</code></dt> | |
| 2663 <dd><p><code>xterm</code> is in most cases built with support for 16 colors. It can also | |
| 2664 be built with support for 88 or 256 colors (but not both). You can try to | |
| 2665 set <code>TERM</code> to either <code>xterm-16color</code>, <code>xterm-88color</code>, or | |
| 2666 <code>xterm-256color</code>. | |
| 2667 </p> | |
| 2668 </dd> | |
| 2669 <dt> <code>rxvt</code></dt> | |
| 2670 <dd><p><code>rxvt</code> is often built with support for 16 colors. You can try to set | |
| 2671 <code>TERM</code> to <code>rxvt-16color</code>. | |
| 2672 </p> | |
| 2673 </dd> | |
| 2674 <dt> <code>konsole</code></dt> | |
| 2675 <dd><p><code>konsole</code> too is often built with support for 16 colors. You can try to | |
| 2676 set <code>TERM</code> to <code>konsole-16color</code> or <code>xterm-16color</code>. | |
| 2677 </p></dd> | |
| 2678 </dl> | |
| 2679 | |
| 2680 <p>After setting <code>TERM</code>, you can verify it by invoking | |
| 2681 ‘<samp>msgcat --color=test</samp>’ and seeing whether the output looks like a | |
| 2682 reasonable color map. | |
| 2683 </p> | |
| 2684 | |
| 2685 <a name="The-_002d_002dstyle-option"></a> | |
| 2686 <a name="SEC160"></a> | |
| 2687 <h3 class="subsection"> <a href="gettext_toc.html#TOC153">9.11.3 The <code>--style</code> option</a> </h3> | |
| 2688 | |
| 2689 <p>The ‘<samp>--style=<var>style_file</var></samp>’ option specifies the style file to use | |
| 2690 when colorizing. It has an effect only when the <code>--color</code> option is | |
| 2691 effective. | |
| 2692 </p> | |
| 2693 <a name="IDX872"></a> | |
| 2694 <p>If the <code>--style</code> option is not specified, the environment variable | |
| 2695 <code>PO_STYLE</code> is considered. It is meant to point to the user's | |
| 2696 preferred style for PO files. | |
| 2697 </p> | |
| 2698 <p>The default style file is ‘<tt>$prefix/share/gettext/styles/po-default.css</tt>’, | |
| 2699 where <code>$prefix</code> is the installation location. | |
| 2700 </p> | |
| 2701 <p>A few style files are predefined: | |
| 2702 </p><dl compact="compact"> | |
| 2703 <dt> ‘<tt>po-vim.css</tt>’</dt> | |
| 2704 <dd><p>This style imitates the look used by vim 7. | |
| 2705 </p> | |
| 2706 </dd> | |
| 2707 <dt> ‘<tt>po-emacs-x.css</tt>’</dt> | |
| 2708 <dd><p>This style imitates the look used by GNU Emacs 21 and 22 in an X11 window. | |
| 2709 </p> | |
| 2710 </dd> | |
| 2711 <dt> ‘<tt>po-emacs-xterm.css</tt>’</dt> | |
| 2712 <dt> ‘<tt>po-emacs-xterm16.css</tt>’</dt> | |
| 2713 <dt> ‘<tt>po-emacs-xterm256.css</tt>’</dt> | |
| 2714 <dd><p>This style imitates the look used by GNU Emacs 22 in a terminal of type | |
| 2715 ‘<samp>xterm</samp>’ (8 colors) or ‘<samp>xterm-16color</samp>’ (16 colors) or | |
| 2716 ‘<samp>xterm-256color</samp>’ (256 colors), respectively. | |
| 2717 </p></dd> | |
| 2718 </dl> | |
| 2719 | |
| 2720 <p>You can use these styles without specifying a directory. They are actually | |
| 2721 located in ‘<tt>$prefix/share/gettext/styles/</tt>’, where <code>$prefix</code> is the | |
| 2722 installation location. | |
| 2723 </p> | |
| 2724 <p>You can also design your own styles. This is described in the next section. | |
| 2725 </p> | |
| 2726 | |
| 2727 | |
| 2728 <a name="Style-rules"></a> | |
| 2729 <a name="SEC161"></a> | |
| 2730 <h3 class="subsection"> <a href="gettext_toc.html#TOC154">9.11.4 Style rules for PO files</a> </h3> | |
| 2731 | |
| 2732 <p>The same style file can be used for styling of a PO file, for terminal | |
| 2733 output and for HTML output. It is written in CSS (Cascading Style Sheet) | |
| 2734 syntax. See <a href="https://www.w3.org/TR/css2/cover.html">https://www.w3.org/TR/css2/cover.html</a> for a formal | |
| 2735 definition of CSS. Many HTML authoring tutorials also contain explanations | |
| 2736 of CSS. | |
| 2737 </p> | |
| 2738 <p>In the case of HTML output, the style file is embedded in the HTML output. | |
| 2739 In the case of text output, the style file is interpreted by the | |
| 2740 <code>msgcat</code> program. This means, in particular, that when | |
| 2741 <code>@import</code> is used with relative file names, the file names are | |
| 2742 </p> | |
| 2743 <ul class="toc"> | |
| 2744 <li>- | |
| 2745 relative to the resulting HTML file, in the case of HTML output, | |
| 2746 | |
| 2747 </li><li>- | |
| 2748 relative to the style sheet containing the <code>@import</code>, in the case of | |
| 2749 text output. (Actually, <code>@import</code>s are not yet supported in this case, | |
| 2750 due to a limitation in <code>libcroco</code>.) | |
| 2751 </li></ul> | |
| 2752 | |
| 2753 <p>CSS rules are built up from selectors and declarations. The declarations | |
| 2754 specify graphical properties; the selectors specify when they apply. | |
| 2755 </p> | |
| 2756 <p>In PO files, the following simple selectors (based on "CSS classes", see | |
| 2757 the CSS2 spec, section 5.8.3) are supported. | |
| 2758 </p> | |
| 2759 <ul> | |
| 2760 <li> | |
| 2761 Selectors that apply to entire messages: | |
| 2762 | |
| 2763 <dl compact="compact"> | |
| 2764 <dt> <code>.header</code></dt> | |
| 2765 <dd><p>This matches the header entry of a PO file. | |
| 2766 </p> | |
| 2767 </dd> | |
| 2768 <dt> <code>.translated</code></dt> | |
| 2769 <dd><p>This matches a translated message. | |
| 2770 </p> | |
| 2771 </dd> | |
| 2772 <dt> <code>.untranslated</code></dt> | |
| 2773 <dd><p>This matches an untranslated message (i.e. a message with empty translation). | |
| 2774 </p> | |
| 2775 </dd> | |
| 2776 <dt> <code>.fuzzy</code></dt> | |
| 2777 <dd><p>This matches a fuzzy message (i.e. a message which has a translation that | |
| 2778 needs review by the translator). | |
| 2779 </p> | |
| 2780 </dd> | |
| 2781 <dt> <code>.obsolete</code></dt> | |
| 2782 <dd><p>This matches an obsolete message (i.e. a message that was translated but is | |
| 2783 not needed by the current POT file any more). | |
| 2784 </p></dd> | |
| 2785 </dl> | |
| 2786 | |
| 2787 </li><li> | |
| 2788 Selectors that apply to parts of a message in PO syntax. Recall the general | |
| 2789 structure of a message in PO syntax: | |
| 2790 | |
| 2791 <table><tr><td> </td><td><pre class="example"><var>white-space</var> | |
| 2792 # <var>translator-comments</var> | |
| 2793 #. <var>extracted-comments</var> | |
| 2794 #: <var>reference</var>… | |
| 2795 #, <var>flag</var>… | |
| 2796 #| msgid <var>previous-untranslated-string</var> | |
| 2797 msgid <var>untranslated-string</var> | |
| 2798 msgstr <var>translated-string</var> | |
| 2799 </pre></td></tr></table> | |
| 2800 | |
| 2801 <dl compact="compact"> | |
| 2802 <dt> <code>.comment</code></dt> | |
| 2803 <dd><p>This matches all comments (translator comments, extracted comments, | |
| 2804 source file reference comments, flag comments, previous message comments, | |
| 2805 as well as the entire obsolete messages). | |
| 2806 </p> | |
| 2807 </dd> | |
| 2808 <dt> <code>.translator-comment</code></dt> | |
| 2809 <dd><p>This matches the translator comments. | |
| 2810 </p> | |
| 2811 </dd> | |
| 2812 <dt> <code>.extracted-comment</code></dt> | |
| 2813 <dd><p>This matches the extracted comments, i.e. the comments placed by the | |
| 2814 programmer at the attention of the translator. | |
| 2815 </p> | |
| 2816 </dd> | |
| 2817 <dt> <code>.reference-comment</code></dt> | |
| 2818 <dd><p>This matches the source file reference comments (entire lines). | |
| 2819 </p> | |
| 2820 </dd> | |
| 2821 <dt> <code>.reference</code></dt> | |
| 2822 <dd><p>This matches the individual source file references inside the source file | |
| 2823 reference comment lines. | |
| 2824 </p> | |
| 2825 </dd> | |
| 2826 <dt> <code>.flag-comment</code></dt> | |
| 2827 <dd><p>This matches the flag comment lines (entire lines). | |
| 2828 </p> | |
| 2829 </dd> | |
| 2830 <dt> <code>.flag</code></dt> | |
| 2831 <dd><p>This matches the individual flags inside flag comment lines. | |
| 2832 </p> | |
| 2833 </dd> | |
| 2834 <dt> <code>.fuzzy-flag</code></dt> | |
| 2835 <dd><p>This matches the `fuzzy' flag inside flag comment lines. | |
| 2836 </p> | |
| 2837 </dd> | |
| 2838 <dt> <code>.previous-comment</code></dt> | |
| 2839 <dd><p>This matches the comments containing the previous untranslated string (entire | |
| 2840 lines). | |
| 2841 </p> | |
| 2842 </dd> | |
| 2843 <dt> <code>.previous</code></dt> | |
| 2844 <dd><p>This matches the previous untranslated string including the string delimiters, | |
| 2845 the associated keywords (<code>msgid</code> etc.) and the spaces between them. | |
| 2846 </p> | |
| 2847 </dd> | |
| 2848 <dt> <code>.msgid</code></dt> | |
| 2849 <dd><p>This matches the untranslated string including the string delimiters, | |
| 2850 the associated keywords (<code>msgid</code> etc.) and the spaces between them. | |
| 2851 </p> | |
| 2852 </dd> | |
| 2853 <dt> <code>.msgstr</code></dt> | |
| 2854 <dd><p>This matches the translated string including the string delimiters, | |
| 2855 the associated keywords (<code>msgstr</code> etc.) and the spaces between them. | |
| 2856 </p> | |
| 2857 </dd> | |
| 2858 <dt> <code>.keyword</code></dt> | |
| 2859 <dd><p>This matches the keywords (<code>msgid</code>, <code>msgstr</code>, etc.). | |
| 2860 </p> | |
| 2861 </dd> | |
| 2862 <dt> <code>.string</code></dt> | |
| 2863 <dd><p>This matches strings, including the string delimiters (double quotes). | |
| 2864 </p></dd> | |
| 2865 </dl> | |
| 2866 | |
| 2867 </li><li> | |
| 2868 Selectors that apply to parts of strings: | |
| 2869 | |
| 2870 <dl compact="compact"> | |
| 2871 <dt> <code>.text</code></dt> | |
| 2872 <dd><p>This matches the entire contents of a string (excluding the string delimiters, | |
| 2873 i.e. the double quotes). | |
| 2874 </p> | |
| 2875 </dd> | |
| 2876 <dt> <code>.escape-sequence</code></dt> | |
| 2877 <dd><p>This matches an escape sequence (starting with a backslash). | |
| 2878 </p> | |
| 2879 </dd> | |
| 2880 <dt> <code>.format-directive</code></dt> | |
| 2881 <dd><p>This matches a format string directive (starting with a ‘<samp>%</samp>’ sign in the | |
| 2882 case of most programming languages, with a ‘<samp>{</samp>’ in the case of | |
| 2883 <code>java-format</code> and <code>csharp-format</code>, with a ‘<samp>~</samp>’ in the case of | |
| 2884 <code>lisp-format</code> and <code>scheme-format</code>, or with ‘<samp>$</samp>’ in the case of | |
| 2885 <code>sh-format</code>). | |
| 2886 </p> | |
| 2887 </dd> | |
| 2888 <dt> <code>.invalid-format-directive</code></dt> | |
| 2889 <dd><p>This matches an invalid format string directive. | |
| 2890 </p> | |
| 2891 </dd> | |
| 2892 <dt> <code>.added</code></dt> | |
| 2893 <dd><p>In an untranslated string, this matches a part of the string that was not | |
| 2894 present in the previous untranslated string. (Not yet implemented in this | |
| 2895 release.) | |
| 2896 </p> | |
| 2897 </dd> | |
| 2898 <dt> <code>.changed</code></dt> | |
| 2899 <dd><p>In an untranslated string or in a previous untranslated string, this matches | |
| 2900 a part of the string that is changed or replaced. (Not yet implemented in | |
| 2901 this release.) | |
| 2902 </p> | |
| 2903 </dd> | |
| 2904 <dt> <code>.removed</code></dt> | |
| 2905 <dd><p>In a previous untranslated string, this matches a part of the string that | |
| 2906 is not present in the current untranslated string. (Not yet implemented in | |
| 2907 this release.) | |
| 2908 </p></dd> | |
| 2909 </dl> | |
| 2910 </li></ul> | |
| 2911 | |
| 2912 <p>These selectors can be combined to hierarchical selectors. For example, | |
| 2913 </p> | |
| 2914 <table><tr><td> </td><td><pre class="smallexample">.msgstr .invalid-format-directive { color: red; } | |
| 2915 </pre></td></tr></table> | |
| 2916 | |
| 2917 <p>will highlight the invalid format directives in the translated strings. | |
| 2918 </p> | |
| 2919 <p>In text mode, pseudo-classes (CSS2 spec, section 5.11) and pseudo-elements | |
| 2920 (CSS2 spec, section 5.12) are not supported. | |
| 2921 </p> | |
| 2922 <p>The declarations in HTML mode are not limited; any graphical attribute | |
| 2923 supported by the browsers can be used. | |
| 2924 </p> | |
| 2925 <p>The declarations in text mode are limited to the following properties. Other | |
| 2926 properties will be silently ignored. | |
| 2927 </p> | |
| 2928 <dl compact="compact"> | |
| 2929 <dt> <code>color</code> (CSS2 spec, section 14.1)</dt> | |
| 2930 <dt> <code>background-color</code> (CSS2 spec, section 14.2.1)</dt> | |
| 2931 <dd><p>These properties is supported. Colors will be adjusted to match the terminal's | |
| 2932 capabilities. Note that many terminals support only 8 colors. | |
| 2933 </p> | |
| 2934 </dd> | |
| 2935 <dt> <code>font-weight</code> (CSS2 spec, section 15.2.3)</dt> | |
| 2936 <dd><p>This property is supported, but most terminals can only render two different | |
| 2937 weights: <code>normal</code> and <code>bold</code>. Values >= 600 are rendered as | |
| 2938 <code>bold</code>. | |
| 2939 </p> | |
| 2940 </dd> | |
| 2941 <dt> <code>font-style</code> (CSS2 spec, section 15.2.3)</dt> | |
| 2942 <dd><p>This property is supported. The values <code>italic</code> and <code>oblique</code> are | |
| 2943 rendered the same way. | |
| 2944 </p> | |
| 2945 </dd> | |
| 2946 <dt> <code>text-decoration</code> (CSS2 spec, section 16.3.1)</dt> | |
| 2947 <dd><p>This property is supported, limited to the values <code>none</code> and | |
| 2948 <code>underline</code>. | |
| 2949 </p></dd> | |
| 2950 </dl> | |
| 2951 | |
| 2952 | |
| 2953 <a name="Customizing-less"></a> | |
| 2954 <a name="SEC162"></a> | |
| 2955 <h3 class="subsection"> <a href="gettext_toc.html#TOC155">9.11.5 Customizing <code>less</code> for viewing PO files</a> </h3> | |
| 2956 | |
| 2957 <p>The ‘<samp>less</samp>’ program is a popular text file browser for use in a text | |
| 2958 screen or terminal emulator. It also supports text with embedded escape | |
| 2959 sequences for colors and text decorations. | |
| 2960 </p> | |
| 2961 <p>You can use <code>less</code> to view a PO file like this (assuming an UTF-8 | |
| 2962 environment): | |
| 2963 </p> | |
| 2964 <table><tr><td> </td><td><pre class="smallexample">msgcat --to-code=UTF-8 --color xyz.po | less -R | |
| 2965 </pre></td></tr></table> | |
| 2966 | |
| 2967 <p>You can simplify this to this simple command: | |
| 2968 </p> | |
| 2969 <table><tr><td> </td><td><pre class="smallexample">less xyz.po | |
| 2970 </pre></td></tr></table> | |
| 2971 | |
| 2972 <p>after these three preparations: | |
| 2973 </p> | |
| 2974 <ol> | |
| 2975 <li> | |
| 2976 Add the options ‘<samp>-R</samp>’ and ‘<samp>-f</samp>’ to the <code>LESS</code> environment | |
| 2977 variable. In sh shells: | |
| 2978 <table><tr><td> </td><td><pre class="smallexample">$ LESS="$LESS -R -f" | |
| 2979 $ export LESS | |
| 2980 </pre></td></tr></table> | |
| 2981 | |
| 2982 </li><li> | |
| 2983 If your system does not already have the ‘<tt>lessopen.sh</tt>’ and | |
| 2984 ‘<tt>lessclose.sh</tt>’ scripts, create them and set the <code>LESSOPEN</code> and | |
| 2985 <code>LESSCLOSE</code> environment variables, as indicated in the manual page | |
| 2986 (‘<samp>man less</samp>’). | |
| 2987 | |
| 2988 </li><li> | |
| 2989 Add to ‘<tt>lessopen.sh</tt>’ a piece of script that recognizes PO files | |
| 2990 through their file extension and invokes <code>msgcat</code> on them, producing | |
| 2991 a temporary file. Like this: | |
| 2992 | |
| 2993 <table><tr><td> </td><td><pre class="smallexample">case "$1" in | |
| 2994 *.po) | |
| 2995 tmpfile=`mktemp "${TMPDIR-/tmp}/less.XXXXXX"` | |
| 2996 msgcat --to-code=UTF-8 --color "$1" > "$tmpfile" | |
| 2997 echo "$tmpfile" | |
| 2998 exit 0 | |
| 2999 ;; | |
| 3000 esac | |
| 3001 </pre></td></tr></table> | |
| 3002 </li></ol> | |
| 3003 | |
| 3004 | |
| 3005 <a name="Other-tools"></a> | |
| 3006 <a name="SEC163"></a> | |
| 3007 <h2 class="section"> <a href="gettext_toc.html#TOC156">9.12 Other tools for manipulating PO files</a> </h2> | |
| 3008 | |
| 3009 <p>The “Pology” package is a Free Software package for manipulating PO files. | |
| 3010 It features, in particular: | |
| 3011 </p> | |
| 3012 <ul class="toc"> | |
| 3013 <li> | |
| 3014 Examination and in-place modification of collections of PO files. | |
| 3015 </li><li> | |
| 3016 Format-aware diffing and patching of PO files. | |
| 3017 </li><li> | |
| 3018 Handling of version-control branches. | |
| 3019 </li><li> | |
| 3020 Fine-grained asynchronous review workflow. | |
| 3021 </li><li> | |
| 3022 Custom translation validation. | |
| 3023 </li><li> | |
| 3024 Language and project specific support. | |
| 3025 </li></ul> | |
| 3026 | |
| 3027 <p>Its home page is at <a href="http://pology.nedohodnik.net/">http://pology.nedohodnik.net/</a>. | |
| 3028 </p> | |
| 3029 | |
| 3030 <a name="libgettextpo"></a> | |
| 3031 <a name="SEC164"></a> | |
| 3032 <h2 class="section"> <a href="gettext_toc.html#TOC157">9.13 Writing your own programs that process PO files</a> </h2> | |
| 3033 | |
| 3034 <p>For the tasks for which a combination of ‘<samp>msgattrib</samp>’, ‘<samp>msgcat</samp>’ etc. | |
| 3035 is not sufficient, a set of C functions is provided in a library, to make it | |
| 3036 possible to process PO files in your own programs. When you use this library, | |
| 3037 you don't need to write routines to parse the PO file; instead, you retrieve | |
| 3038 a pointer in memory to each of messages contained in the PO file. Functions | |
| 3039 for writing those memory structures to a file after working with them are | |
| 3040 provided too. | |
| 3041 </p> | |
| 3042 <p>The functions are declared in the header file ‘<samp><gettext-po.h></samp>’, and are | |
| 3043 defined in a library called ‘<samp>libgettextpo</samp>’. | |
| 3044 </p> | |
| 3045 | |
| 3046 <p>The following example shows code how these functions can be used. Error | |
| 3047 handling code is omitted, as its implementation is delegated to the user | |
| 3048 provided functions. | |
| 3049 </p> | |
| 3050 <table><tr><td> </td><td><pre class="example">struct po_xerror_handler handler = | |
| 3051 { | |
| 3052 .xerror = …, | |
| 3053 .xerror2 = … | |
| 3054 }; | |
| 3055 const char *filename = …; | |
| 3056 /* Read the file into memory. */ | |
| 3057 po_file_t file = po_file_read (filename, &handler); | |
| 3058 | |
| 3059 { | |
| 3060 const char * const *domains = po_file_domains (file); | |
| 3061 const char * const *domainp; | |
| 3062 | |
| 3063 /* Iterate the domains contained in the file. */ | |
| 3064 for (domainp = domains; *domainp; domainp++) | |
| 3065 { | |
| 3066 po_message_t *message; | |
| 3067 const char *domain = *domainp; | |
| 3068 po_message_iterator_t iterator = po_message_iterator (file, domain); | |
| 3069 | |
| 3070 /* Iterate each message inside the domain. */ | |
| 3071 while ((message = po_next_message (iterator)) != NULL) | |
| 3072 { | |
| 3073 /* Read data from the message … */ | |
| 3074 const char *msgid = po_message_msgid (message); | |
| 3075 const char *msgstr = po_message_msgstr (message); | |
| 3076 | |
| 3077 … | |
| 3078 | |
| 3079 /* Modify its contents … */ | |
| 3080 if (perform_some_tests (msgid, msgstr)) | |
| 3081 po_message_set_fuzzy (message, 1); | |
| 3082 | |
| 3083 … | |
| 3084 } | |
| 3085 /* Always release returned po_message_iterator_t. */ | |
| 3086 po_message_iterator_free (iterator); | |
| 3087 } | |
| 3088 | |
| 3089 /* Write back the result. */ | |
| 3090 po_file_t result = po_file_write (file, filename, &handler); | |
| 3091 } | |
| 3092 | |
| 3093 /* Always release the returned po_file_t. */ | |
| 3094 po_file_free (file); | |
| 3095 </pre></td></tr></table> | |
| 3096 | |
| 3097 | |
| 3098 <a name="Error-Handling"></a> | |
| 3099 <a name="SEC165"></a> | |
| 3100 <h3 class="subsection"> <a href="gettext_toc.html#TOC158">9.13.1 Error Handling</a> </h3> | |
| 3101 | |
| 3102 <p>Error management is performed through callbacks provided by the user of | |
| 3103 the library. They are provided through a parameter with the following | |
| 3104 type: | |
| 3105 </p> | |
| 3106 <dl> | |
| 3107 <dt><u>Data Type:</u> <b>struct</b><i> po_xerror_handler</i> | |
| 3108 <a name="IDX873"></a> | |
| 3109 </dt> | |
| 3110 <dd><p>Its pointer is defined as <code>po_xerror_handler_t</code>. Contains | |
| 3111 two fields, <code>xerror</code> and <code>xerror2</code>, with the following function | |
| 3112 signatures. | |
| 3113 </p></dd></dl> | |
| 3114 | |
| 3115 <dl> | |
| 3116 <dt><u>Function:</u> void <b>xerror</b><i> (int <var>severity</var>, po_message_t <var>message</var>, const char *<var>filename</var>, size_t <var>lineno</var>, size_t <var>column</var>, int <var>multiline_p</var>, const char *<var>message_text</var>)</i> | |
| 3117 <a name="IDX874"></a> | |
| 3118 </dt> | |
| 3119 <dd><p>This function is called to signal a problem of the given <var>severity</var>. | |
| 3120 It <em>must not return</em> if <var>severity</var> is | |
| 3121 <code>PO_SEVERITY_FATAL_ERROR</code>. | |
| 3122 </p> | |
| 3123 <p><var>message_text</var> is the problem description. When <var>multiline_p</var> | |
| 3124 is true, it can contain multiple lines of text, each terminated with a | |
| 3125 newline, otherwise a single line. | |
| 3126 </p> | |
| 3127 <p><var>message</var> and/or <var>filename</var> and <var>lineno</var> indicate where the | |
| 3128 problem occurred: | |
| 3129 </p> | |
| 3130 <ul> | |
| 3131 <li> | |
| 3132 If <var>filename</var> is <code>NULL</code>, <var>filename</var> and <var>lineno</var> and | |
| 3133 <var>column</var> should be ignored. | |
| 3134 | |
| 3135 </li><li> | |
| 3136 If <var>lineno</var> is <code>(size_t)(-1)</code>, <var>lineno</var> and <var>column</var> | |
| 3137 should be ignored. | |
| 3138 | |
| 3139 </li><li> | |
| 3140 If <var>column</var> is <code>(size_t)(-1)</code>, it should be ignored. | |
| 3141 </li></ul> | |
| 3142 </dd></dl> | |
| 3143 | |
| 3144 <dl> | |
| 3145 <dt><u>Function:</u> void <b>xerror2</b><i> (int <var>severity</var>, po_message_t <var>message1</var>, const char *<var>filename1</var>, size_t <var>lineno1</var>, size_t <var>column1</var>, int <var>multiline_p1</var>, const char *<var>message_text1</var>, po_message_t <var>message2</var>, const char *<var>filename2</var>, size_t <var>lineno2</var>, size_t <var>column2</var>, int <var>multiline_p2</var>, const char *<var>message_text2</var>)</i> | |
| 3146 <a name="IDX875"></a> | |
| 3147 </dt> | |
| 3148 <dd><p>This function is called to signal a problem of the given <var>severity</var> | |
| 3149 that refers to two messages. It <em>must not return</em> if | |
| 3150 <var>severity</var> is <code>PO_SEVERITY_FATAL_ERROR</code>. | |
| 3151 </p> | |
| 3152 <p>It is similar to two calls to xerror. If possible, an ellipsis can be | |
| 3153 appended to <var>message_text1</var> and prepended to <var>message_text2</var>. | |
| 3154 </p></dd></dl> | |
| 3155 | |
| 3156 | |
| 3157 <a name="po_005ffile_005ft-API"></a> | |
| 3158 <a name="SEC166"></a> | |
| 3159 <h3 class="subsection"> <a href="gettext_toc.html#TOC159">9.13.2 po_file_t API</a> </h3> | |
| 3160 | |
| 3161 <dl> | |
| 3162 <dt><u>Data Type:</u> <b>po_file_t</b> | |
| 3163 <a name="IDX876"></a> | |
| 3164 </dt> | |
| 3165 <dd><p>This is a pointer type that refers to the contents of a PO file, after it has | |
| 3166 been read into memory. | |
| 3167 </p></dd></dl> | |
| 3168 | |
| 3169 <dl> | |
| 3170 <dt><u>Function:</u> po_file_t <b>po_file_create</b><i> ()</i> | |
| 3171 <a name="IDX877"></a> | |
| 3172 </dt> | |
| 3173 <dd><p>The <code>po_file_create</code> function creates an empty PO file representation in | |
| 3174 memory. | |
| 3175 </p></dd></dl> | |
| 3176 | |
| 3177 <dl> | |
| 3178 <dt><u>Function:</u> po_file_t <b>po_file_read</b><i> (const char *<var>filename</var>, struct po_xerror_handler *<var>handler</var>)</i> | |
| 3179 <a name="IDX878"></a> | |
| 3180 </dt> | |
| 3181 <dd><p>The <code>po_file_read</code> function reads a PO file into memory. The file name | |
| 3182 is given as argument. The return value is a handle to the PO file's contents, | |
| 3183 valid until <code>po_file_free</code> is called on it. In case of error, the | |
| 3184 functions from <var>handler</var> are called to signal it. | |
| 3185 </p> | |
| 3186 <p>This function is exported as ‘<samp>po_file_read_v3</samp>’ at ABI level, but is | |
| 3187 defined as <code>po_file_read</code> in C code after the inclusion of | |
| 3188 ‘<samp><gettext-po.h></samp>’. | |
| 3189 </p></dd></dl> | |
| 3190 | |
| 3191 <dl> | |
| 3192 <dt><u>Function:</u> po_file_t <b>po_file_write</b><i> (po_file_t <var>file</var>, const char *<var>filename</var>, struct po_xerror_handler *<var>handler</var>)</i> | |
| 3193 <a name="IDX879"></a> | |
| 3194 </dt> | |
| 3195 <dd><p>The <code>po_file_write</code> function writes the contents of the memory | |
| 3196 structure <var>file</var> the <var>filename</var> given. The return value is | |
| 3197 <var>file</var> after a successful operation. In case of error, the | |
| 3198 functions from <var>handler</var> are called to signal it. | |
| 3199 </p> | |
| 3200 <p>This function is exported as ‘<samp>po_file_write_v2</samp>’ at ABI level, but | |
| 3201 is defined as <code>po_file_write</code> in C code after the inclusion of | |
| 3202 ‘<samp><gettext-po.h></samp>’. | |
| 3203 </p></dd></dl> | |
| 3204 | |
| 3205 <dl> | |
| 3206 <dt><u>Function:</u> void <b>po_file_free</b><i> (po_file_t <var>file</var>)</i> | |
| 3207 <a name="IDX880"></a> | |
| 3208 </dt> | |
| 3209 <dd><p>The <code>po_file_free</code> function frees a PO file's contents from memory, | |
| 3210 including all messages that are only implicitly accessible through iterators. | |
| 3211 </p></dd></dl> | |
| 3212 | |
| 3213 <dl> | |
| 3214 <dt><u>Function:</u> const char * const * <b>po_file_domains</b><i> (po_file_t <var>file</var>)</i> | |
| 3215 <a name="IDX881"></a> | |
| 3216 </dt> | |
| 3217 <dd><p>The <code>po_file_domains</code> function returns the domains for which the given | |
| 3218 PO file has messages. The return value is a <code>NULL</code> terminated array | |
| 3219 which is valid as long as the <var>file</var> handle is valid. For PO files which | |
| 3220 contain no ‘<samp>domain</samp>’ directive, the return value contains only one domain, | |
| 3221 namely the default domain <code>"messages"</code>. | |
| 3222 </p></dd></dl> | |
| 3223 | |
| 3224 | |
| 3225 <a name="po_005fmessage_005fiterator_005ft-API"></a> | |
| 3226 <a name="SEC167"></a> | |
| 3227 <h3 class="subsection"> <a href="gettext_toc.html#TOC160">9.13.3 po_message_iterator_t API</a> </h3> | |
| 3228 | |
| 3229 <dl> | |
| 3230 <dt><u>Data Type:</u> <b>po_message_iterator_t</b> | |
| 3231 <a name="IDX882"></a> | |
| 3232 </dt> | |
| 3233 <dd><p>This is a pointer type that refers to an iterator that produces a sequence of | |
| 3234 messages. | |
| 3235 </p></dd></dl> | |
| 3236 | |
| 3237 <dl> | |
| 3238 <dt><u>Function:</u> po_message_iterator_t <b>po_message_iterator</b><i> (po_file_t <var>file</var>, const char *<var>domain</var>)</i> | |
| 3239 <a name="IDX883"></a> | |
| 3240 </dt> | |
| 3241 <dd><p>The <code>po_message_iterator</code> returns an iterator that will produce the | |
| 3242 messages of <var>file</var> that belong to the given <var>domain</var>. If <var>domain</var> | |
| 3243 is <code>NULL</code>, the default domain is used instead. To list the messages, | |
| 3244 use the function <code>po_next_message</code> repeatedly. | |
| 3245 </p></dd></dl> | |
| 3246 | |
| 3247 <dl> | |
| 3248 <dt><u>Function:</u> void <b>po_message_iterator_free</b><i> (po_message_iterator_t <var>iterator</var>)</i> | |
| 3249 <a name="IDX884"></a> | |
| 3250 </dt> | |
| 3251 <dd><p>The <code>po_message_iterator_free</code> function frees an iterator previously | |
| 3252 allocated through the <code>po_message_iterator</code> function. | |
| 3253 </p></dd></dl> | |
| 3254 | |
| 3255 <dl> | |
| 3256 <dt><u>Function:</u> po_message_t <b>po_next_message</b><i> (po_message_iterator_t <var>iterator</var>)</i> | |
| 3257 <a name="IDX885"></a> | |
| 3258 </dt> | |
| 3259 <dd><p>The <code>po_next_message</code> function returns the next message from | |
| 3260 <var>iterator</var> and advances the iterator. It returns <code>NULL</code> when the | |
| 3261 iterator has reached the end of its message list. | |
| 3262 </p></dd></dl> | |
| 3263 | |
| 3264 | |
| 3265 <a name="po_005fmessage_005ft-API"></a> | |
| 3266 <a name="SEC168"></a> | |
| 3267 <h3 class="subsection"> <a href="gettext_toc.html#TOC161">9.13.4 po_message_t API</a> </h3> | |
| 3268 | |
| 3269 <dl> | |
| 3270 <dt><u>Data Type:</u> <b>po_message_t</b> | |
| 3271 <a name="IDX886"></a> | |
| 3272 </dt> | |
| 3273 <dd><p>This is a pointer type that refers to a message of a PO file, including its | |
| 3274 translation. | |
| 3275 </p></dd></dl> | |
| 3276 | |
| 3277 <dl> | |
| 3278 <dt><u>Function:</u> po_message_t <b>po_message_create</b><i> (void)</i> | |
| 3279 <a name="IDX887"></a> | |
| 3280 </dt> | |
| 3281 <dd><p>Returns a freshly constructed message. To finish initializing the | |
| 3282 message, you must set the <code>msgid</code> and <code>msgstr</code>. It <em>must</em> be | |
| 3283 inserted into a file to manage its memory, as there is no | |
| 3284 <code>po_message_free</code> available to the user of the library. | |
| 3285 </p></dd></dl> | |
| 3286 | |
| 3287 <p>The following functions access details of a <code>po_message_t</code>. Recall | |
| 3288 that the results are valid as long as the <var>file</var> handle is valid. | |
| 3289 </p> | |
| 3290 <dl> | |
| 3291 <dt><u>Function:</u> const char * <b>po_message_msgctxt</b><i> (po_message_t <var>message</var>)</i> | |
| 3292 <a name="IDX888"></a> | |
| 3293 </dt> | |
| 3294 <dd><p>The <code>po_message_msgctxt</code> function returns the <code>msgctxt</code>, the | |
| 3295 context of <var>message</var>. Returns <code>NULL</code> for a message not restricted | |
| 3296 to a context. | |
| 3297 </p></dd></dl> | |
| 3298 | |
| 3299 <dl> | |
| 3300 <dt><u>Function:</u> void <b>po_message_set_msgctxt</b><i> (po_message_t <var>message</var>, const char *<var>msgctxt</var>)</i> | |
| 3301 <a name="IDX889"></a> | |
| 3302 </dt> | |
| 3303 <dd><p>The <code>po_message_set_msgctxt</code> function changes the <code>msgctxt</code>, | |
| 3304 the context of the message, to the value provided through | |
| 3305 <var>msgctxt</var>. The value <code>NULL</code> removes the restriction. | |
| 3306 </p></dd></dl> | |
| 3307 | |
| 3308 <dl> | |
| 3309 <dt><u>Function:</u> const char * <b>po_message_msgid</b><i> (po_message_t <var>message</var>)</i> | |
| 3310 <a name="IDX890"></a> | |
| 3311 </dt> | |
| 3312 <dd><p>The <code>po_message_msgid</code> function returns the <code>msgid</code> (untranslated | |
| 3313 English string) of <var>message</var>. This is guaranteed to be non-<code>NULL</code>. | |
| 3314 </p></dd></dl> | |
| 3315 | |
| 3316 <dl> | |
| 3317 <dt><u>Function:</u> void <b>po_message_set_msgid</b><i> (po_message_t <var>message</var>, const char *<var>msgid</var>)</i> | |
| 3318 <a name="IDX891"></a> | |
| 3319 </dt> | |
| 3320 <dd><p>The <code>po_message_set_msgid</code> function changes the <code>msgid</code> | |
| 3321 (untranslated English string) of <var>message</var> to the value provided through | |
| 3322 <var>msgid</var>, a non-<code>NULL</code> string. | |
| 3323 </p></dd></dl> | |
| 3324 | |
| 3325 <dl> | |
| 3326 <dt><u>Function:</u> const char * <b>po_message_msgid_plural</b><i> (po_message_t <var>message</var>)</i> | |
| 3327 <a name="IDX892"></a> | |
| 3328 </dt> | |
| 3329 <dd><p>The <code>po_message_msgid_plural</code> function returns the <code>msgid_plural</code> | |
| 3330 (untranslated English plural string) of <var>message</var>, a message with plurals, | |
| 3331 or <code>NULL</code> for a message without plural. | |
| 3332 </p></dd></dl> | |
| 3333 | |
| 3334 <dl> | |
| 3335 <dt><u>Function:</u> void <b>po_message_set_msgid_plural</b><i> (po_message_t <var>message</var>, const char *<var>msgid_plural</var>)</i> | |
| 3336 <a name="IDX893"></a> | |
| 3337 </dt> | |
| 3338 <dd><p>The <code>po_message_set_msgid_plural</code> function changes the | |
| 3339 <code>msgid_plural</code> (untranslated English plural string) of a message to | |
| 3340 the value provided through <var>msgid_plural</var>, or removes the plurals if | |
| 3341 <code>NULL</code> is provided as <var>msgid_plural</var>. | |
| 3342 </p></dd></dl> | |
| 3343 | |
| 3344 <dl> | |
| 3345 <dt><u>Function:</u> const char * <b>po_message_msgstr</b><i> (po_message_t <var>message</var>)</i> | |
| 3346 <a name="IDX894"></a> | |
| 3347 </dt> | |
| 3348 <dd><p>The <code>po_message_msgstr</code> function returns the <code>msgstr</code> (translation) | |
| 3349 of <var>message</var>. For an untranslated message, the return value is an empty | |
| 3350 string. | |
| 3351 </p></dd></dl> | |
| 3352 | |
| 3353 <dl> | |
| 3354 <dt><u>Function:</u> void <b>po_message_set_msgstr</b><i> (po_message_t <var>message</var>, const char *<var>msgstr</var>)</i> | |
| 3355 <a name="IDX895"></a> | |
| 3356 </dt> | |
| 3357 <dd><p>The <code>po_message_set_msgstr</code> function changes the <code>msgstr</code> | |
| 3358 (translation) of <var>message</var> to the value provided through <var>msgstr</var>, a | |
| 3359 non-<code>NULL</code> string. | |
| 3360 </p></dd></dl> | |
| 3361 | |
| 3362 <dl> | |
| 3363 <dt><u>Function:</u> const char * <b>po_message_msgstr_plural</b><i> (po_message_t <var>message</var>, int <var>index</var>)</i> | |
| 3364 <a name="IDX896"></a> | |
| 3365 </dt> | |
| 3366 <dd><p>The <code>po_message_msgstr_plural</code> function returns the | |
| 3367 <code>msgstr[<var>index</var>]</code> of <var>message</var>, a message with plurals, or | |
| 3368 <code>NULL</code> when the <var>index</var> is out of range or for a message without | |
| 3369 plural. | |
| 3370 </p></dd></dl> | |
| 3371 | |
| 3372 <dl> | |
| 3373 <dt><u>Function:</u> void <b>po_message_set_msgstr_plural</b><i> (po_message_t <var>message</var>, int <var>index</var>, const char *<var>msgstr_plural</var>)</i> | |
| 3374 <a name="IDX897"></a> | |
| 3375 </dt> | |
| 3376 <dd><p>The <code>po_message_set_msgstr_plural</code> function changes the | |
| 3377 <code>msgstr[<var>index</var>]</code> of <var>message</var>, a message with plurals, to | |
| 3378 the value provided through <var>msgstr_plural</var>. <var>message</var> must be a | |
| 3379 message with plurals. | |
| 3380 Use <code>NULL</code> as the value of <var>msgstr_plural</var> with | |
| 3381 <var>index</var> pointing to the last element to reduce the number of plural | |
| 3382 forms. | |
| 3383 </p></dd></dl> | |
| 3384 | |
| 3385 <dl> | |
| 3386 <dt><u>Function:</u> const char * <b>po_message_comments</b><i> (po_message_t <var>message</var>)</i> | |
| 3387 <a name="IDX898"></a> | |
| 3388 </dt> | |
| 3389 <dd><p>The <code>po_message_comments</code> function returns the comments of <var>message</var>, | |
| 3390 a multiline string, ending in a newline, or a non-<code>NULL</code> empty string. | |
| 3391 </p></dd></dl> | |
| 3392 | |
| 3393 <dl> | |
| 3394 <dt><u>Function:</u> void <b>po_message_set_comments</b><i> (po_message_t <var>message</var>, const char *<var>comments</var>)</i> | |
| 3395 <a name="IDX899"></a> | |
| 3396 </dt> | |
| 3397 <dd><p>The <code>po_message_set_comments</code> function changes the comments of | |
| 3398 <var>message</var> to the value <var>comments</var>, a multiline string, ending in a | |
| 3399 newline, or a non-<code>NULL</code> empty string. | |
| 3400 </p></dd></dl> | |
| 3401 | |
| 3402 <dl> | |
| 3403 <dt><u>Function:</u> const char * <b>po_message_extracted_comments</b><i> (po_message_t <var>message</var>)</i> | |
| 3404 <a name="IDX900"></a> | |
| 3405 </dt> | |
| 3406 <dd><p>The <code>po_message_extracted_comments</code> function returns the extracted | |
| 3407 comments of <var>message</var>, a multiline string, ending in a newline, or a | |
| 3408 non-<code>NULL</code> empty string. | |
| 3409 </p></dd></dl> | |
| 3410 | |
| 3411 <dl> | |
| 3412 <dt><u>Function:</u> void <b>po_message_set_extracted_comments</b><i> (po_message_t <var>message</var>, const char *<var>extracted_comments</var>)</i> | |
| 3413 <a name="IDX901"></a> | |
| 3414 </dt> | |
| 3415 <dd><p>The <code>po_message_set_extracted_comments</code> function changes the | |
| 3416 comments of <var>message</var> to the value <var>extracted_comments</var>, a multiline | |
| 3417 string, ending in a newline, or a non-<code>NULL</code> empty string. | |
| 3418 </p></dd></dl> | |
| 3419 | |
| 3420 <dl> | |
| 3421 <dt><u>Function:</u> const char * <b>po_message_prev_msgctxt</b><i> (po_message_t <var>message</var>)</i> | |
| 3422 <a name="IDX902"></a> | |
| 3423 </dt> | |
| 3424 <dd><p>The <code>po_message_prev_msgctxt</code> function returns the previous | |
| 3425 <code>msgctxt</code>, the previous context of <var>message</var>. Return | |
| 3426 <code>NULL</code> for a message that does not have a previous context. | |
| 3427 </p></dd></dl> | |
| 3428 | |
| 3429 <dl> | |
| 3430 <dt><u>Function:</u> void <b>po_message_set_prev_msgctxt</b><i> (po_message_t <var>message</var>, const char *<var>prev_msgctxt</var>)</i> | |
| 3431 <a name="IDX903"></a> | |
| 3432 </dt> | |
| 3433 <dd><p>The <code>po_message_set_prev_msgctxt</code> function changes the previous | |
| 3434 <code>msgctxt</code>, the context of the message, to the value provided | |
| 3435 through <var>prev_msgctxt</var>. The value <code>NULL</code> removes the stored | |
| 3436 previous msgctxt. | |
| 3437 </p></dd></dl> | |
| 3438 | |
| 3439 <dl> | |
| 3440 <dt><u>Function:</u> const char * <b>po_message_prev_msgid</b><i> (po_message_t <var>message</var>)</i> | |
| 3441 <a name="IDX904"></a> | |
| 3442 </dt> | |
| 3443 <dd><p>The <code>po_message_prev_msgid</code> function returns the previous | |
| 3444 <code>msgid</code> (untranslated English string) of <var>message</var>, or | |
| 3445 <code>NULL</code> if there is no previous <code>msgid</code> stored. | |
| 3446 </p></dd></dl> | |
| 3447 | |
| 3448 <dl> | |
| 3449 <dt><u>Function:</u> void <b>po_message_set_prev_msgid</b><i> (po_message_t <var>message</var>, const char *<var>prev_msgid</var>)</i> | |
| 3450 <a name="IDX905"></a> | |
| 3451 </dt> | |
| 3452 <dd><p>The <code>po_message_set_prev_msgid</code> function changes the previous | |
| 3453 <code>msgid</code> (untranslated English string) of <var>message</var> to the value | |
| 3454 provided through <var>prev_msgid</var>, or removes the message when it is | |
| 3455 <code>NULL</code>. | |
| 3456 </p></dd></dl> | |
| 3457 | |
| 3458 <dl> | |
| 3459 <dt><u>Function:</u> const char * <b>po_message_prev_msgid_plural</b><i> (po_message_t <var>message</var>)</i> | |
| 3460 <a name="IDX906"></a> | |
| 3461 </dt> | |
| 3462 <dd><p>The <code>po_message_prev_msgid_plural</code> function returns the previous | |
| 3463 <code>msgid_plural</code> (untranslated English plural string) of | |
| 3464 <var>message</var>, a message with plurals, or <code>NULL</code> for a message | |
| 3465 without plural without any stored previous <code>msgid_plural</code>. | |
| 3466 </p></dd></dl> | |
| 3467 | |
| 3468 <dl> | |
| 3469 <dt><u>Function:</u> void <b>po_message_set_prev_msgid_plural</b><i> (po_message_t <var>message</var>, const char *<var>prev_msgid_plural</var>)</i> | |
| 3470 <a name="IDX907"></a> | |
| 3471 </dt> | |
| 3472 <dd><p>The <code>po_message_set_prev_msgid_plural</code> function changes the | |
| 3473 previous <code>msgid_plural</code> (untranslated English plural string) of a | |
| 3474 message to the value provided through <var>prev_msgid_plural</var>, or | |
| 3475 removes the stored previous <code>msgid_plural</code> if <code>NULL</code> is | |
| 3476 provided as <var>prev_msgid_plural</var>. | |
| 3477 </p></dd></dl> | |
| 3478 | |
| 3479 <dl> | |
| 3480 <dt><u>Function:</u> int <b>po_message_is_obsolete</b><i> (po_message_t <var>message</var>)</i> | |
| 3481 <a name="IDX908"></a> | |
| 3482 </dt> | |
| 3483 <dd><p>The <code>po_message_is_obsolete</code> function returns true when <var>message</var> | |
| 3484 is marked as obsolete. | |
| 3485 </p></dd></dl> | |
| 3486 | |
| 3487 <dl> | |
| 3488 <dt><u>Function:</u> void <b>po_message_set_obsolete</b><i> (po_message_t <var>message</var>, int <var>obsolete</var>)</i> | |
| 3489 <a name="IDX909"></a> | |
| 3490 </dt> | |
| 3491 <dd><p>The <code>po_message_set_obsolete</code> function changes the obsolete mark of | |
| 3492 <var>message</var>. | |
| 3493 </p></dd></dl> | |
| 3494 | |
| 3495 <dl> | |
| 3496 <dt><u>Function:</u> int <b>po_message_is_fuzzy</b><i> (po_message_t <var>message</var>)</i> | |
| 3497 <a name="IDX910"></a> | |
| 3498 </dt> | |
| 3499 <dd><p>The <code>po_message_is_fuzzy</code> function returns true when <var>message</var> | |
| 3500 is marked as fuzzy. | |
| 3501 </p></dd></dl> | |
| 3502 | |
| 3503 <dl> | |
| 3504 <dt><u>Function:</u> void <b>po_message_set_fuzzy</b><i> (po_message_t <var>message</var>, int <var>fuzzy</var>)</i> | |
| 3505 <a name="IDX911"></a> | |
| 3506 </dt> | |
| 3507 <dd><p>The <code>po_message_set_fuzzy</code> function changes the fuzzy mark of | |
| 3508 <var>message</var>. | |
| 3509 </p></dd></dl> | |
| 3510 | |
| 3511 <dl> | |
| 3512 <dt><u>Function:</u> int <b>po_message_is_format</b><i> (po_message_t <var>message</var>, const char *<var>format_type</var>)</i> | |
| 3513 <a name="IDX912"></a> | |
| 3514 </dt> | |
| 3515 <dd><p>The <code>po_message_is_format</code> function returns true when the message | |
| 3516 is marked as being a format string of <var>format_type</var>. | |
| 3517 </p></dd></dl> | |
| 3518 | |
| 3519 <dl> | |
| 3520 <dt><u>Function:</u> void <b>po_message_set_format</b><i> (po_message_t <var>message</var>, const char *<var>format_type</var>, int <var>value</var>)</i> | |
| 3521 <a name="IDX913"></a> | |
| 3522 </dt> | |
| 3523 <dd><p>The <code>po_message_set_fuzzy</code> function changes the format mark of | |
| 3524 the message for the <var>format_type</var> provided. | |
| 3525 </p></dd></dl> | |
| 3526 | |
| 3527 <dl> | |
| 3528 <dt><u>Function:</u> int <b>po_message_is_range</b><i> (po_message_t <var>message</var>, int *<var>minp</var>, int *<var>maxp</var>)</i> | |
| 3529 <a name="IDX914"></a> | |
| 3530 </dt> | |
| 3531 <dd><p>The <code>po_message_is_range</code> function returns true when the message | |
| 3532 has a numeric range set, and stores the minimum and maximum value in the | |
| 3533 locations pointed by <var>minp</var> and <var>maxp</var> respectively. | |
| 3534 </p></dd></dl> | |
| 3535 | |
| 3536 <dl> | |
| 3537 <dt><u>Function:</u> void <b>po_message_set_range</b><i> (po_message_t <var>message</var>, int <var>min</var>, int <var>max</var>)</i> | |
| 3538 <a name="IDX915"></a> | |
| 3539 </dt> | |
| 3540 <dd><p>The <code>po_message_set_range</code> function changes the numeric range of | |
| 3541 the message. <var>min</var> and <var>max</var> must be non-negative, with | |
| 3542 <var>min</var> < <var>max</var>. Use <var>min</var> and <var>max</var> with value <code>-1</code> | |
| 3543 to remove the numeric range of <var>message</var>. | |
| 3544 </p></dd></dl> | |
| 3545 | |
| 3546 | |
| 3547 <a name="PO-Header-Entry-API"></a> | |
| 3548 <a name="SEC169"></a> | |
| 3549 <h3 class="subsection"> <a href="gettext_toc.html#TOC162">9.13.5 PO Header Entry API</a> </h3> | |
| 3550 | |
| 3551 <p>The following functions provide an interface to extract and manipulate | |
| 3552 the header entry (see section <a href="gettext_6.html#SEC52">Filling in the Header Entry</a>) from a file loaded in memory. | |
| 3553 The meta information must be written back into the domain message with | |
| 3554 the empty string as <code>msgid</code>. | |
| 3555 </p> | |
| 3556 <dl> | |
| 3557 <dt><u>Function:</u> const char * <b>po_file_domain_header</b><i> (po_file_t <var>file</var>, const char *<var>domain</var>)</i> | |
| 3558 <a name="IDX916"></a> | |
| 3559 </dt> | |
| 3560 <dd><p>Returns the header entry of a domain from <var>file</var>, a PO file loaded in | |
| 3561 memory. The value <code>NULL</code> provided as <var>domain</var> denotes the | |
| 3562 default domain. Returns <code>NULL</code> if there is no header entry. | |
| 3563 </p></dd></dl> | |
| 3564 | |
| 3565 <dl> | |
| 3566 <dt><u>Function:</u> char * <b>po_header_field</b><i> (const char *<var>header</var>, const char *<var>field</var>)</i> | |
| 3567 <a name="IDX917"></a> | |
| 3568 </dt> | |
| 3569 <dd><p>Returns the value of <var>field</var> in the <var>header</var> entry. The return | |
| 3570 value is either a freshly allocated string, to be freed by the caller, | |
| 3571 or <code>NULL</code>. | |
| 3572 </p></dd></dl> | |
| 3573 | |
| 3574 <dl> | |
| 3575 <dt><u>Function:</u> char * <b>po_header_set_field</b><i> (const char *<var>header</var>, const char *<var>field</var>, const char *<var>value</var>)</i> | |
| 3576 <a name="IDX918"></a> | |
| 3577 </dt> | |
| 3578 <dd><p>Returns a freshly allocated string which contains the entry from | |
| 3579 <var>header</var> with <var>field</var> set to <var>value</var>. The field is added if | |
| 3580 necessary. | |
| 3581 </p></dd></dl> | |
| 3582 | |
| 3583 | |
| 3584 <a name="po_005ffilepos_005ft-API"></a> | |
| 3585 <a name="SEC170"></a> | |
| 3586 <h3 class="subsection"> <a href="gettext_toc.html#TOC163">9.13.6 po_filepos_t API</a> </h3> | |
| 3587 | |
| 3588 <dl> | |
| 3589 <dt><u>Data Type:</u> <b>po_filepos_t</b> | |
| 3590 <a name="IDX919"></a> | |
| 3591 </dt> | |
| 3592 <dd><p>This is a pointer type that refers to a string's position within a | |
| 3593 source file. | |
| 3594 </p></dd></dl> | |
| 3595 | |
| 3596 <p>The following functions provide an interface to extract and manipulate | |
| 3597 these references. | |
| 3598 </p> | |
| 3599 <dl> | |
| 3600 <dt><u>Function:</u> po_filepos_t <b>po_message_filepos</b><i> (po_message_t <var>message</var>, int <var>index</var>)</i> | |
| 3601 <a name="IDX920"></a> | |
| 3602 </dt> | |
| 3603 <dd><p>Returns the file reference in position <var>index</var> from the message. If | |
| 3604 <var>index</var> is out of range, returns <code>NULL</code>. | |
| 3605 </p></dd></dl> | |
| 3606 | |
| 3607 <dl> | |
| 3608 <dt><u>Function:</u> void <b>po_message_remove_filepos</b><i> (po_message_t <var>message</var>, int <var>index</var>)</i> | |
| 3609 <a name="IDX921"></a> | |
| 3610 </dt> | |
| 3611 <dd><p>Removes the file reference in position <var>index</var> from the message. It | |
| 3612 moves all references following <var>index</var> one position backwards. | |
| 3613 </p></dd></dl> | |
| 3614 | |
| 3615 <dl> | |
| 3616 <dt><u>Function:</u> void <b>po_message_add_filepos</b><i> (po_message_t <var>message</var>, const char *<var>file</var>, size_t <var>start_line</var>)</i> | |
| 3617 <a name="IDX922"></a> | |
| 3618 </dt> | |
| 3619 <dd><p>Adds a reference to the string from <var>file</var> starting at | |
| 3620 <var>start_line</var>, if it is not already present for the message. The | |
| 3621 value <code>(size_t)(-1)</code> for <var>start_line</var> denotes that the line | |
| 3622 number is not available. | |
| 3623 </p></dd></dl> | |
| 3624 | |
| 3625 | |
| 3626 <a name="Format-Type-API"></a> | |
| 3627 <a name="SEC171"></a> | |
| 3628 <h3 class="subsection"> <a href="gettext_toc.html#TOC164">9.13.7 Format Type API</a> </h3> | |
| 3629 | |
| 3630 <dl> | |
| 3631 <dt><u>Function:</u> const char * const * <b>po_format_list</b><i> (void)</i> | |
| 3632 <a name="IDX923"></a> | |
| 3633 </dt> | |
| 3634 <dd><p>Returns a <code>NULL</code> terminated array of the supported format types. | |
| 3635 </p></dd></dl> | |
| 3636 | |
| 3637 <dl> | |
| 3638 <dt><u>Function:</u> const char * <b>po_format_pretty_name</b><i> (const char *<var>format_type</var>)</i> | |
| 3639 <a name="IDX924"></a> | |
| 3640 </dt> | |
| 3641 <dd><p>Returns the pretty name associated with <var>format_type</var>. For example, | |
| 3642 it returns “C#” when <var>format_type</var> is “csharp_format”. | |
| 3643 Return <code>NULL</code> if <var>format_type</var> is not a supported format type. | |
| 3644 </p></dd></dl> | |
| 3645 | |
| 3646 | |
| 3647 <a name="Checking-API"></a> | |
| 3648 <a name="SEC172"></a> | |
| 3649 <h3 class="subsection"> <a href="gettext_toc.html#TOC165">9.13.8 Checking API</a> </h3> | |
| 3650 | |
| 3651 <dl> | |
| 3652 <dt><u>Function:</u> void <b>po_file_check_all</b><i> (po_file_t <var>file</var>, po_xerror_handler_t <var>handler</var>)</i> | |
| 3653 <a name="IDX925"></a> | |
| 3654 </dt> | |
| 3655 <dd><p>Tests whether the entire <var>file</var> is valid, like <code>msgfmt</code> does it. If it | |
| 3656 is invalid, passes the reasons to <var>handler</var>. | |
| 3657 </p></dd></dl> | |
| 3658 | |
| 3659 <dl> | |
| 3660 <dt><u>Function:</u> void <b>po_message_check_all</b><i> (po_message_t <var>message</var>, po_message_iterator_t <var>iterator</var>, po_xerror_handler_t <var>handler</var>)</i> | |
| 3661 <a name="IDX926"></a> | |
| 3662 </dt> | |
| 3663 <dd><p>Tests <var>message</var>, to be inserted at <var>iterator</var> in a PO file in memory, | |
| 3664 like <code>msgfmt</code> does it. If it is invalid, passes the reasons to | |
| 3665 <var>handler</var>. <var>iterator</var> is not modified by this call; it only | |
| 3666 specifies the file and the domain. | |
| 3667 </p></dd></dl> | |
| 3668 | |
| 3669 <dl> | |
| 3670 <dt><u>Function:</u> void <b>po_message_check_format</b><i> (po_message_t <var>message</var>, po_xerror_handler_t <var>handler</var>)</i> | |
| 3671 <a name="IDX927"></a> | |
| 3672 </dt> | |
| 3673 <dd><p>Tests whether the message translation from <var>message</var> is a valid | |
| 3674 format string if the message is marked as being a format string. If it | |
| 3675 is invalid, passes the reasons to <var>handler</var>. | |
| 3676 </p> | |
| 3677 <p>This function is exported as ‘<samp>po_message_check_format_v2</samp>’ at ABI | |
| 3678 level, but is defined as <code>po_message_check_format</code> in C code after | |
| 3679 the inclusion of ‘<samp><gettext-po.h></samp>’. | |
| 3680 </p></dd></dl> | |
| 3681 | |
| 3682 | |
| 3683 <table cellpadding="1" cellspacing="1" border="0"> | |
| 3684 <tr><td valign="middle" align="left">[<a href="#SEC87" title="Beginning of this chapter or previous chapter"> << </a>]</td> | |
| 3685 <td valign="middle" align="left">[<a href="gettext_10.html#SEC173" title="Next chapter"> >> </a>]</td> | |
| 3686 <td valign="middle" align="left"> </td> | |
| 3687 <td valign="middle" align="left"> </td> | |
| 3688 <td valign="middle" align="left"> </td> | |
| 3689 <td valign="middle" align="left"> </td> | |
| 3690 <td valign="middle" align="left"> </td> | |
| 3691 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td> | |
| 3692 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td> | |
| 3693 <td valign="middle" align="left">[<a href="gettext_21.html#SEC389" title="Index">Index</a>]</td> | |
| 3694 <td valign="middle" align="left">[<a href="gettext_abt.html#SEC_About" title="About (help)"> ? </a>]</td> | |
| 3695 </tr></table> | |
| 3696 <p> | |
| 3697 <font size="-1"> | |
| 3698 This document was generated by <em>Bruno Haible</em> on <em>February, 21 2024</em> using <a href="https://www.nongnu.org/texi2html/"><em>texi2html 1.78a</em></a>. | |
| 3699 </font> | |
| 3700 <br> | |
| 3701 | |
| 3702 </p> | |
| 3703 </body> | |
| 3704 </html> |