X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9838df2cefc5b368bb11f98c784ecc78f45ecaf7..bae2dc62af49b5a870bbabd9473a92921736a6f0:/docs/html/gettext/gettext_4.html diff --git a/docs/html/gettext/gettext_4.html b/docs/html/gettext/gettext_4.html new file mode 100644 index 0000000000..72b1a78791 --- /dev/null +++ b/docs/html/gettext/gettext_4.html @@ -0,0 +1,337 @@ +<HTML> +<HEAD> +<!-- This HTML file has been created by texi2html 1.54 + from gettext.texi on 25 January 1999 --> + +<TITLE>GNU gettext utilities - Making the Initial PO File</TITLE> +<link href="gettext_5.html" rel=Next> +<link href="gettext_3.html" rel=Previous> +<link href="gettext_toc.html" rel=ToC> + +</HEAD> +<BODY> +<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>. +<P><HR><P> + + +<H1><A NAME="SEC19" HREF="gettext_toc.html#TOC19">Making the Initial PO File</A></H1> + + + +<H2><A NAME="SEC20" HREF="gettext_toc.html#TOC20">Invoking the <CODE>xgettext</CODE> Program</A></H2> + + +<PRE> +xgettext [<VAR>option</VAR>] <VAR>inputfile</VAR> ... +</PRE> + +<DL COMPACT> + +<DT><SAMP>`-a'</SAMP> +<DD> +<DT><SAMP>`--extract-all'</SAMP> +<DD> +Extract all strings. + +<DT><SAMP>`-c [<VAR>tag</VAR>]'</SAMP> +<DD> +<DT><SAMP>`--add-comments[=<VAR>tag</VAR>]'</SAMP> +<DD> +Place comment block with <VAR>tag</VAR> (or those preceding keyword lines) +in output file. + +<DT><SAMP>`-C'</SAMP> +<DD> +<DT><SAMP>`--c++'</SAMP> +<DD> +Recognize C++ style comments. + +<DT><SAMP>`--debug'</SAMP> +<DD> +Use the flags <KBD>c-format</KBD> and <KBD>possible-c-format</KBD> to show who was +responsible for marking a message as a format string. The later form is +used if the <CODE>xgettext</CODE> program decided, the format form is used if +the programmer prescribed it. + +By default only the <KBD>c-format</KBD> form is used. The translator should +not have to care about these details. + +<DT><SAMP>`-d <VAR>name</VAR>'</SAMP> +<DD> +<DT><SAMP>`--default-domain=<VAR>name</VAR>'</SAMP> +<DD> +Use <TT>`<VAR>name</VAR>.po'</TT> for output (instead of <TT>`messages.po'</TT>). + +The special domain name <TT>`-'</TT> or <TT>`/dev/stdout'</TT> means to write +the output to <TT>`stdout'</TT>. + +<DT><SAMP>`-D <VAR>directory</VAR>'</SAMP> +<DD> +<DT><SAMP>`--directory=<VAR>directory</VAR>'</SAMP> +<DD> +Change to <VAR>directory</VAR> before beginning to search and scan source +files. The resulting <TT>`.po'</TT> file will be written relative to the +original directory, though. + +<DT><SAMP>`-f <VAR>file</VAR>'</SAMP> +<DD> +<DT><SAMP>`--files-from=<VAR>file</VAR>'</SAMP> +<DD> +Read the names of the input files from <VAR>file</VAR> instead of getting +them from the command line. + +<DT><SAMP>`--force'</SAMP> +<DD> +Always write output file even if no message is defined. + +<DT><SAMP>`-h'</SAMP> +<DD> +<DT><SAMP>`--help'</SAMP> +<DD> +Display this help and exit. + +<DT><SAMP>`-I <VAR>list</VAR>'</SAMP> +<DD> +<DT><SAMP>`--input-path=<VAR>list</VAR>'</SAMP> +<DD> +List of directories searched for input files. + +<DT><SAMP>`-j'</SAMP> +<DD> +<DT><SAMP>`--join-existing'</SAMP> +<DD> +Join messages with existing file. + +<DT><SAMP>`-k <VAR>word</VAR>'</SAMP> +<DD> +<DT><SAMP>`--keyword[=<VAR>word</VAR>]'</SAMP> +<DD> +Additional keyword to be looked for (without <VAR>word</VAR> means not to +use default keywords). + +The default keywords, which are always looked for if not explicitly +disabled, are <CODE>gettext</CODE>, <CODE>dgettext</CODE>, <CODE>dcgettext</CODE> and +<CODE>gettext_noop</CODE>. + +<DT><SAMP>`-m [<VAR>string</VAR>]'</SAMP> +<DD> +<DT><SAMP>`--msgstr-prefix[=<VAR>string</VAR>]'</SAMP> +<DD> +Use <VAR>string</VAR> or "" as prefix for msgstr entries. + +<DT><SAMP>`-M [<VAR>string</VAR>]'</SAMP> +<DD> +<DT><SAMP>`--msgstr-suffix[=<VAR>string</VAR>]'</SAMP> +<DD> +Use <VAR>string</VAR> or "" as suffix for msgstr entries. + +<DT><SAMP>`--no-location'</SAMP> +<DD> +Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>'</SAMP> lines. + +<DT><SAMP>`-n'</SAMP> +<DD> +<DT><SAMP>`--add-location'</SAMP> +<DD> +Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>'</SAMP> lines (default). + +<DT><SAMP>`--omit-header'</SAMP> +<DD> +Don't write header with <SAMP>`msgid ""'</SAMP> entry. + +This is useful for testing purposes because it eliminates a source +of variance for generated <CODE>.gmo</CODE> files. We can ship some of +these files in the GNU <CODE>gettext</CODE> package, and the result of +regenerating them through <CODE>msgfmt</CODE> should yield the same values. + +<DT><SAMP>`-p <VAR>dir</VAR>'</SAMP> +<DD> +<DT><SAMP>`--output-dir=<VAR>dir</VAR>'</SAMP> +<DD> +Output files will be placed in directory <VAR>dir</VAR>. + +<DT><SAMP>`-s'</SAMP> +<DD> +<DT><SAMP>`--sort-output'</SAMP> +<DD> +Generate sorted output and remove duplicates. + +<DT><SAMP>`--strict'</SAMP> +<DD> +Write out strict Uniforum conforming PO file. + +<DT><SAMP>`-v'</SAMP> +<DD> +<DT><SAMP>`--version'</SAMP> +<DD> +Output version information and exit. + +<DT><SAMP>`-x <VAR>file</VAR>'</SAMP> +<DD> +<DT><SAMP>`--exclude-file=<VAR>file</VAR>'</SAMP> +<DD> +Entries from <VAR>file</VAR> are not extracted. + +</DL> + +<P> +Search path for supplementary PO files is: +<TT>`/usr/local/share/nls/src/'</TT>. + +</P> +<P> +If <VAR>inputfile</VAR> is <SAMP>`-'</SAMP>, standard input is read. + +</P> +<P> +This implementation of <CODE>xgettext</CODE> is able to process a few awkward +cases, like strings in preprocessor macros, ANSI concatenation of +adjacent strings, and escaped end of lines for continued strings. + +</P> + + +<H2><A NAME="SEC21" HREF="gettext_toc.html#TOC21">C Sources Context</A></H2> + +<P> +PO mode is particularly powerful when used with PO files +created through GNU <CODE>gettext</CODE> utilities, as those utilities +insert special comments in the PO files they generate. +Some of these special comments relate the PO file entry to +exactly where the untranslated string appears in the program sources. + +</P> +<P> +When the translator gets to an untranslated entry, she is fairly +often faced with an original string which is not as informative as +it normally should be, being succinct, cryptic, or otherwise ambiguous. +Before choosing how to translate the string, she needs to understand +better what the string really means and how tight the translation has +to be. Most of the time, when problems arise, the only way left to make +her judgment is looking at the true program sources from where this +string originated, searching for surrounding comments the programmer +might have put in there, and looking around for helping clues of +<EM>any</EM> kind. + +</P> +<P> +Surely, when looking at program sources, the translator will receive +more help if she is a fluent programmer. However, even if she is +not versed in programming and feels a little lost in C code, the +translator should not be shy at taking a look, once in a while. +It is most probable that she will still be able to find some of the +hints she needs. She will learn quickly to not feel uncomfortable +in program code, paying more attention to programmer's comments, +variable and function names (if he dared choosing them well), and +overall organization, than to the program code itself. + +</P> +<P> +The following commands are meant to help the translator at getting +program source context for a PO file entry. + +</P> +<DL COMPACT> + +<DT><KBD>s</KBD> +<DD> +Resume the display of a program source context, or cycle through them. + +<DT><KBD>M-s</KBD> +<DD> +Display of a program source context selected by menu. + +<DT><KBD>S</KBD> +<DD> +Add a directory to the search path for source files. + +<DT><KBD>M-S</KBD> +<DD> +Delete a directory from the search path for source files. + +</DL> + +<P> +The commands <KBD>s</KBD> (<CODE>po-cycle-reference</CODE>) and <KBD>M-s</KBD> +(<CODE>po-select-source-reference</CODE>) both open another window displaying +some source program file, and already positioned in such a way that +it shows an actual use of the string to be translated. By doing +so, the command gives source program context for the string. But if +the entry has no source context references, or if all references +are unresolved along the search path for program sources, then the +command diagnoses this as an error. + +</P> +<P> +Even if <KBD>s</KBD> (or <KBD>M-s</KBD>) opens a new window, the cursor stays +in the PO file window. If the translator really wants to +get into the program source window, she ought to do it explicitly, +maybe by using command <KBD>O</KBD>. + +</P> +<P> +When <KBD>s</KBD> is typed for the first time, or for a PO file entry which +is different of the last one used for getting source context, then the +command reacts by giving the first context available for this entry, +if any. If some context has already been recently displayed for the +current PO file entry, and the translator wandered off to do other +things, typing <KBD>s</KBD> again will merely resume, in another window, +the context last displayed. In particular, if the translator moved +the cursor away from the context in the source file, the command will +bring the cursor back to the context. By using <KBD>s</KBD> many times +in a row, with no other commands intervening, PO mode will cycle to +the next available contexts for this particular entry, getting back +to the first context once the last has been shown. + +</P> +<P> +The command <KBD>M-s</KBD> behaves differently. Instead of cycling through +references, it lets the translator choose of particular reference among +many, and displays that reference. It is best used with completion, +if the translator types <KBD>TAB</KBD> immediately after <KBD>M-s</KBD>, in +response to the question, she will be offered a menu of all possible +references, as a reminder of which are the acceptable answers. +This command is useful only where there are really many contexts +available for a single string to translate. + +</P> +<P> +Program source files are usually found relative to where the PO +file stands. As a special provision, when this fails, the file is +also looked for, but relative to the directory immediately above it. +Those two cases take proper care of most PO files. However, it might +happen that a PO file has been moved, or is edited in a different +place than its normal location. When this happens, the translator +should tell PO mode in which directory normally sits the genuine PO +file. Many such directories may be specified, and all together, they +constitute what is called the <STRONG>search path</STRONG> for program sources. +The command <KBD>S</KBD> (<CODE>po-consider-source-path</CODE>) is used to interactively +enter a new directory at the front of the search path, and the command +<KBD>M-S</KBD> (<CODE>po-ignore-source-path</CODE>) is used to select, with completion, +one of the directories she does not want anymore on the search path. + +</P> + + +<H2><A NAME="SEC22" HREF="gettext_toc.html#TOC22">Using Translation Compendiums</A></H2> + +<P> +Compendiums are yet to be implemented. + +</P> +<P> +An incoming PO mode feature will let the translator maintain a +compendium of already achieved translations. A <STRONG>compendium</STRONG> +is a special PO file containing a set of translations recurring in +many different packages. The translator will be given commands for +adding entries to her compendium, and later initializing untranslated +entries, or updating already translated entries, from translations +kept in the compendium. For this to work, however, the compendium +would have to be normalized. See section <A HREF="gettext_2.html#SEC12">Normalizing Strings in Entries</A>. + +</P> + +<P><HR><P> +<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>. +</BODY> +</HTML>