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