mirror of
https://github.com/Stichting-MINIX-Research-Foundation/netbsd.git
synced 2025-09-12 00:24:52 -04:00
1596 lines
53 KiB
HTML
1596 lines
53 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<!-- This HTML file has been created by texi2html 1.52a
|
|
from gettext.texi on 11 April 2005 -->
|
|
|
|
<TITLE>GNU gettext utilities - 6 Updating Existing PO Files</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_5.html">previous</A>, <A HREF="gettext_7.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
|
|
<P><HR><P>
|
|
|
|
|
|
<H1><A NAME="SEC40" HREF="gettext_toc.html#TOC40">6 Updating Existing PO Files</A></H1>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC41" HREF="gettext_toc.html#TOC41">6.1 Invoking the <CODE>msgmerge</CODE> Program</A></H2>
|
|
|
|
<P>
|
|
<A NAME="IDX295"></A>
|
|
<A NAME="IDX296"></A>
|
|
|
|
<PRE>
|
|
msgmerge [<VAR>option</VAR>] <VAR>def</VAR>.po <VAR>ref</VAR>.pot
|
|
</PRE>
|
|
|
|
<P>
|
|
The <CODE>msgmerge</CODE> program merges two Uniforum style .po files together.
|
|
The <VAR>def</VAR>.po file is an existing PO file with translations which will
|
|
be taken over to the newly created file as long as they still match;
|
|
comments will be preserved, but extracted comments and file positions will
|
|
be discarded. The <VAR>ref</VAR>.pot file is the last created PO file with
|
|
up-to-date source references but old translations, or a PO Template file
|
|
(generally created by <CODE>xgettext</CODE>); any translations or comments
|
|
in the file will be discarded, however dot comments and file positions
|
|
will be preserved. Where an exact match cannot be found, fuzzy matching
|
|
is used to produce better results.
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC42" HREF="gettext_toc.html#TOC42">6.1.1 Input file location</A></H3>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><SAMP>`<VAR>def</VAR>.po´</SAMP>
|
|
<DD>
|
|
Translations referring to old sources.
|
|
|
|
<DT><SAMP>`<VAR>ref</VAR>.pot´</SAMP>
|
|
<DD>
|
|
References to the new sources.
|
|
|
|
<DT><SAMP>`-D <VAR>directory</VAR>´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--directory=<VAR>directory</VAR>´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX297"></A>
|
|
<A NAME="IDX298"></A>
|
|
Add <VAR>directory</VAR> to the list of directories. Source files are
|
|
searched relative to this list of directories. The resulting <TT>`.po´</TT>
|
|
file will be written relative to the current directory, though.
|
|
|
|
<DT><SAMP>`-C <VAR>file</VAR>´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--compendium=<VAR>file</VAR>´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX299"></A>
|
|
<A NAME="IDX300"></A>
|
|
Specify an additional library of message translations. See section <A HREF="gettext_6.html#SEC59">6.11 Using Translation Compendia</A>.
|
|
This option may be specified more than once.
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC43" HREF="gettext_toc.html#TOC43">6.1.2 Operation mode</A></H3>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><SAMP>`-U´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--update´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX301"></A>
|
|
<A NAME="IDX302"></A>
|
|
Update <VAR>def</VAR>.po. Do nothing if <VAR>def</VAR>.po is already up to date.
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC44" HREF="gettext_toc.html#TOC44">6.1.3 Output file location</A></H3>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><SAMP>`-o <VAR>file</VAR>´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--output-file=<VAR>file</VAR>´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX303"></A>
|
|
<A NAME="IDX304"></A>
|
|
Write output to specified file.
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="IDX305"></A>
|
|
The results are written to standard output if no output file is specified
|
|
or if it is <SAMP>`-´</SAMP>.
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC45" HREF="gettext_toc.html#TOC45">6.1.4 Output file location in update mode</A></H3>
|
|
|
|
<P>
|
|
The result is written back to <VAR>def</VAR>.po.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><SAMP>`--backup=<VAR>control</VAR>´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX306"></A>
|
|
<A NAME="IDX307"></A>
|
|
Make a backup of <VAR>def</VAR>.po
|
|
|
|
<DT><SAMP>`--suffix=<VAR>suffix</VAR>´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX308"></A>
|
|
Override the usual backup suffix.
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="IDX309"></A>
|
|
The version control method may be selected via the <CODE>--backup</CODE> option
|
|
or through the <CODE>VERSION_CONTROL</CODE> environment variable. Here are the
|
|
values:
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><SAMP>`none´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`off´</SAMP>
|
|
<DD>
|
|
Never make backups (even if <CODE>--backup</CODE> is given).
|
|
|
|
<DT><SAMP>`numbered´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`t´</SAMP>
|
|
<DD>
|
|
Make numbered backups.
|
|
|
|
<DT><SAMP>`existing´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`nil´</SAMP>
|
|
<DD>
|
|
Make numbered backups if numbered backups for this file already exist,
|
|
otherwise make simple backups.
|
|
|
|
<DT><SAMP>`simple´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`never´</SAMP>
|
|
<DD>
|
|
Always make simple backups.
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
The backup suffix is <SAMP>`~´</SAMP>, unless set with <CODE>--suffix</CODE> or the
|
|
<CODE>SIMPLE_BACKUP_SUFFIX</CODE> environment variable.
|
|
|
|
</P>
|
|
|
|
|
|
<H3><A NAME="SEC46" HREF="gettext_toc.html#TOC46">6.1.5 Operation modifiers</A></H3>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><SAMP>`-m´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--multi-domain´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX310"></A>
|
|
<A NAME="IDX311"></A>
|
|
Apply <VAR>ref</VAR>.pot to each of the domains in <VAR>def</VAR>.po.
|
|
|
|
<DT><SAMP>`-N´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--no-fuzzy-matching´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX312"></A>
|
|
<A NAME="IDX313"></A>
|
|
Do not use fuzzy matching when an exact match is not found. This may speed
|
|
up the operation considerably.
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC47" HREF="gettext_toc.html#TOC47">6.1.6 Input file syntax</A></H3>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><SAMP>`-P´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--properties-input´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX314"></A>
|
|
<A NAME="IDX315"></A>
|
|
Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE>
|
|
syntax, not in PO file syntax.
|
|
|
|
<DT><SAMP>`--stringtable-input´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX316"></A>
|
|
Assume the input files are NeXTstep/GNUstep localized resource files in
|
|
<CODE>.strings</CODE> syntax, not in PO file syntax.
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC48" HREF="gettext_toc.html#TOC48">6.1.7 Output details</A></H3>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><SAMP>`--force-po´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX317"></A>
|
|
Always write an output file even if it contains no message.
|
|
|
|
<DT><SAMP>`-i´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--indent´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX318"></A>
|
|
<A NAME="IDX319"></A>
|
|
Write the .po file using indented style.
|
|
|
|
<DT><SAMP>`--no-location´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX320"></A>
|
|
Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines.
|
|
|
|
<DT><SAMP>`--add-location´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX321"></A>
|
|
Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines (default).
|
|
|
|
<DT><SAMP>`--strict´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX322"></A>
|
|
Write out a strict Uniforum conforming PO file. Note that this
|
|
Uniforum format should be avoided because it doesn't support the
|
|
GNU extensions.
|
|
|
|
<DT><SAMP>`-p´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--properties-output´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX323"></A>
|
|
<A NAME="IDX324"></A>
|
|
Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
|
|
that this file format doesn't support plural forms and silently drops
|
|
obsolete messages.
|
|
|
|
<DT><SAMP>`--stringtable-output´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX325"></A>
|
|
Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
|
|
Note that this file format doesn't support plural forms.
|
|
|
|
<DT><SAMP>`-w <VAR>number</VAR>´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--width=<VAR>number</VAR>´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX326"></A>
|
|
<A NAME="IDX327"></A>
|
|
Set the output page width. Long strings in the output files will be
|
|
split across multiple lines in order to ensure that each line's width
|
|
(= number of screen columns) is less or equal to the given <VAR>number</VAR>.
|
|
|
|
<DT><SAMP>`--no-wrap´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX328"></A>
|
|
Do not break long message lines. Message lines whose width exceeds the
|
|
output page width will not be split into several lines. Only file reference
|
|
lines which are wider than the output page width will be split.
|
|
|
|
<DT><SAMP>`-s´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--sort-output´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX329"></A>
|
|
<A NAME="IDX330"></A>
|
|
<A NAME="IDX331"></A>
|
|
Generate sorted output. Note that using this option makes it much harder
|
|
for the translator to understand each message's context.
|
|
|
|
<DT><SAMP>`-F´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--sort-by-file´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX332"></A>
|
|
<A NAME="IDX333"></A>
|
|
Sort output by file location.
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC49" HREF="gettext_toc.html#TOC49">6.1.8 Informative output</A></H3>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><SAMP>`-h´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--help´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX334"></A>
|
|
<A NAME="IDX335"></A>
|
|
Display this help and exit.
|
|
|
|
<DT><SAMP>`-V´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--version´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX336"></A>
|
|
<A NAME="IDX337"></A>
|
|
Output version information and exit.
|
|
|
|
<DT><SAMP>`-v´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--verbose´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX338"></A>
|
|
<A NAME="IDX339"></A>
|
|
Increase verbosity level.
|
|
|
|
<DT><SAMP>`-q´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--quiet´</SAMP>
|
|
<DD>
|
|
<DT><SAMP>`--silent´</SAMP>
|
|
<DD>
|
|
<A NAME="IDX340"></A>
|
|
<A NAME="IDX341"></A>
|
|
<A NAME="IDX342"></A>
|
|
Suppress progress indicators.
|
|
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC50" HREF="gettext_toc.html#TOC50">6.2 Translated Entries</A></H2>
|
|
<P>
|
|
<A NAME="IDX343"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Each PO file entry for which the <CODE>msgstr</CODE> field has been filled with
|
|
a translation, and which is not marked as fuzzy (see section <A HREF="gettext_6.html#SEC51">6.3 Fuzzy Entries</A>),
|
|
is said to be a <EM>translated</EM> entry. Only translated entries will
|
|
later be compiled by GNU <CODE>msgfmt</CODE> and become usable in programs.
|
|
Other entry types will be excluded; translation will not occur for them.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX344"></A>
|
|
Some commands are more specifically related to translated entry processing.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><KBD>t</KBD>
|
|
<DD>
|
|
<A NAME="IDX345"></A>
|
|
Find the next translated entry (<CODE>po-next-translated-entry</CODE>).
|
|
|
|
<DT><KBD>T</KBD>
|
|
<DD>
|
|
<A NAME="IDX346"></A>
|
|
Find the previous translated entry (<CODE>po-previous-translated-entry</CODE>).
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="IDX347"></A>
|
|
<A NAME="IDX348"></A>
|
|
<A NAME="IDX349"></A>
|
|
<A NAME="IDX350"></A>
|
|
The commands <KBD>t</KBD> (<CODE>po-next-translated-entry</CODE>) and <KBD>T</KBD>
|
|
(<CODE>po-previous-translated-entry</CODE>) move forwards or backwards, chasing
|
|
for an translated entry. If none is found, the search is extended and
|
|
wraps around in the PO file buffer.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX351"></A>
|
|
Translated entries usually result from the translator having edited in
|
|
a translation for them, section <A HREF="gettext_6.html#SEC54">6.6 Modifying Translations</A>. However, if the
|
|
variable <CODE>po-auto-fuzzy-on-edit</CODE> is not <CODE>nil</CODE>, the entry having
|
|
received a new translation first becomes a fuzzy entry, which ought to
|
|
be later unfuzzied before becoming an official, genuine translated entry.
|
|
See section <A HREF="gettext_6.html#SEC51">6.3 Fuzzy Entries</A>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC51" HREF="gettext_toc.html#TOC51">6.3 Fuzzy Entries</A></H2>
|
|
<P>
|
|
<A NAME="IDX352"></A>
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX353"></A>
|
|
<A NAME="IDX354"></A>
|
|
Each PO file entry may have a set of <EM>attributes</EM>, which are
|
|
qualities given a name and explicitly associated with the translation,
|
|
using a special system comment. One of these attributes
|
|
has the name <CODE>fuzzy</CODE>, and entries having this attribute are said
|
|
to have a fuzzy translation. They are called fuzzy entries, for short.
|
|
|
|
</P>
|
|
<P>
|
|
Fuzzy entries, even if they account for translated entries for
|
|
most other purposes, usually call for revision by the translator.
|
|
Those may be produced by applying the program <CODE>msgmerge</CODE> to
|
|
update an older translated PO files according to a new PO template
|
|
file, when this tool hypothesises that some new <CODE>msgid</CODE> has
|
|
been modified only slightly out of an older one, and chooses to pair
|
|
what it thinks to be the old translation for the new modified entry.
|
|
The slight alteration in the original string (the <CODE>msgid</CODE> string)
|
|
should often be reflected in the translated string, and this requires
|
|
the intervention of the translator. For this reason, <CODE>msgmerge</CODE>
|
|
might mark some entries as being fuzzy.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX355"></A>
|
|
Also, the translator may decide herself to mark an entry as fuzzy
|
|
for her own convenience, when she wants to remember that the entry
|
|
has to be later revisited. So, some commands are more specifically
|
|
related to fuzzy entry processing.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><KBD>z</KBD>
|
|
<DD>
|
|
<A NAME="IDX356"></A>
|
|
Find the next fuzzy entry (<CODE>po-next-fuzzy-entry</CODE>).
|
|
|
|
<DT><KBD>Z</KBD>
|
|
<DD>
|
|
<A NAME="IDX357"></A>
|
|
Find the previous fuzzy entry (<CODE>po-previous-fuzzy-entry</CODE>).
|
|
|
|
<DT><KBD><KBD>TAB</KBD></KBD>
|
|
<DD>
|
|
<A NAME="IDX358"></A>
|
|
Remove the fuzzy attribute of the current entry (<CODE>po-unfuzzy</CODE>).
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="IDX359"></A>
|
|
<A NAME="IDX360"></A>
|
|
<A NAME="IDX361"></A>
|
|
<A NAME="IDX362"></A>
|
|
The commands <KBD>z</KBD> (<CODE>po-next-fuzzy-entry</CODE>) and <KBD>Z</KBD>
|
|
(<CODE>po-previous-fuzzy-entry</CODE>) move forwards or backwards, chasing for
|
|
a fuzzy entry. If none is found, the search is extended and wraps
|
|
around in the PO file buffer.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX363"></A>
|
|
<A NAME="IDX364"></A>
|
|
<A NAME="IDX365"></A>
|
|
The command <KBD><KBD>TAB</KBD></KBD> (<CODE>po-unfuzzy</CODE>) removes the fuzzy
|
|
attribute associated with an entry, usually leaving it translated.
|
|
Further, if the variable <CODE>po-auto-select-on-unfuzzy</CODE> has not
|
|
the <CODE>nil</CODE> value, the <KBD><KBD>TAB</KBD></KBD> command will automatically chase
|
|
for another interesting entry to work on. The initial value of
|
|
<CODE>po-auto-select-on-unfuzzy</CODE> is <CODE>nil</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
The initial value of <CODE>po-auto-fuzzy-on-edit</CODE> is <CODE>nil</CODE>. However,
|
|
if the variable <CODE>po-auto-fuzzy-on-edit</CODE> is set to <CODE>t</CODE>, any entry
|
|
edited through the <KBD><KBD>RET</KBD></KBD> command is marked fuzzy, as a way to
|
|
ensure some kind of double check, later. In this case, the usual paradigm
|
|
is that an entry becomes fuzzy (if not already) whenever the translator
|
|
modifies it. If she is satisfied with the translation, she then uses
|
|
<KBD><KBD>TAB</KBD></KBD> to pick another entry to work on, clearing the fuzzy attribute
|
|
on the same blow. If she is not satisfied yet, she merely uses <KBD><KBD>SPC</KBD></KBD>
|
|
to chase another entry, leaving the entry fuzzy.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX366"></A>
|
|
<A NAME="IDX367"></A>
|
|
The translator may also use the <KBD><KBD>DEL</KBD></KBD> command
|
|
(<CODE>po-fade-out-entry</CODE>) over any translated entry to mark it as being
|
|
fuzzy, when she wants to easily leave a trace she wants to later return
|
|
working at this entry.
|
|
|
|
</P>
|
|
<P>
|
|
Also, when time comes to quit working on a PO file buffer with the <KBD>q</KBD>
|
|
command, the translator is asked for confirmation, if fuzzy string
|
|
still exists.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC52" HREF="gettext_toc.html#TOC52">6.4 Untranslated Entries</A></H2>
|
|
<P>
|
|
<A NAME="IDX368"></A>
|
|
|
|
</P>
|
|
<P>
|
|
When <CODE>xgettext</CODE> originally creates a PO file, unless told
|
|
otherwise, it initializes the <CODE>msgid</CODE> field with the untranslated
|
|
string, and leaves the <CODE>msgstr</CODE> string to be empty. Such entries,
|
|
having an empty translation, are said to be <EM>untranslated</EM> entries.
|
|
Later, when the programmer slightly modifies some string right in
|
|
the program, this change is later reflected in the PO file
|
|
by the appearance of a new untranslated entry for the modified string.
|
|
|
|
</P>
|
|
<P>
|
|
The usual commands moving from entry to entry consider untranslated
|
|
entries on the same level as active entries. Untranslated entries
|
|
are easily recognizable by the fact they end with <SAMP>`msgstr ""´</SAMP>.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX369"></A>
|
|
The work of the translator might be (quite naively) seen as the process
|
|
of seeking for an untranslated entry, editing a translation for
|
|
it, and repeating these actions until no untranslated entries remain.
|
|
Some commands are more specifically related to untranslated entry
|
|
processing.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><KBD>u</KBD>
|
|
<DD>
|
|
<A NAME="IDX370"></A>
|
|
Find the next untranslated entry (<CODE>po-next-untranslated-entry</CODE>).
|
|
|
|
<DT><KBD>U</KBD>
|
|
<DD>
|
|
<A NAME="IDX371"></A>
|
|
Find the previous untranslated entry (<CODE>po-previous-untransted-entry</CODE>).
|
|
|
|
<DT><KBD>k</KBD>
|
|
<DD>
|
|
<A NAME="IDX372"></A>
|
|
Turn the current entry into an untranslated one (<CODE>po-kill-msgstr</CODE>).
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="IDX373"></A>
|
|
<A NAME="IDX374"></A>
|
|
<A NAME="IDX375"></A>
|
|
<A NAME="IDX376"></A>
|
|
The commands <KBD>u</KBD> (<CODE>po-next-untranslated-entry</CODE>) and <KBD>U</KBD>
|
|
(<CODE>po-previous-untransted-entry</CODE>) move forwards or backwards,
|
|
chasing for an untranslated entry. If none is found, the search is
|
|
extended and wraps around in the PO file buffer.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX377"></A>
|
|
<A NAME="IDX378"></A>
|
|
An entry can be turned back into an untranslated entry by
|
|
merely emptying its translation, using the command <KBD>k</KBD>
|
|
(<CODE>po-kill-msgstr</CODE>). See section <A HREF="gettext_6.html#SEC54">6.6 Modifying Translations</A>.
|
|
|
|
</P>
|
|
<P>
|
|
Also, when time comes to quit working on a PO file buffer
|
|
with the <KBD>q</KBD> command, the translator is asked for confirmation,
|
|
if some untranslated string still exists.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC53" HREF="gettext_toc.html#TOC53">6.5 Obsolete Entries</A></H2>
|
|
<P>
|
|
<A NAME="IDX379"></A>
|
|
|
|
</P>
|
|
<P>
|
|
By <EM>obsolete</EM> PO file entries, we mean those entries which are
|
|
commented out, usually by <CODE>msgmerge</CODE> when it found that the
|
|
translation is not needed anymore by the package being localized.
|
|
|
|
</P>
|
|
<P>
|
|
The usual commands moving from entry to entry consider obsolete
|
|
entries on the same level as active entries. Obsolete entries are
|
|
easily recognizable by the fact that all their lines start with
|
|
<CODE>#</CODE>, even those lines containing <CODE>msgid</CODE> or <CODE>msgstr</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
Commands exist for emptying the translation or reinitializing it
|
|
to the original untranslated string. Commands interfacing with the
|
|
kill ring may force some previously saved text into the translation.
|
|
The user may interactively edit the translation. All these commands
|
|
may apply to obsolete entries, carefully leaving the entry obsolete
|
|
after the fact.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX380"></A>
|
|
Moreover, some commands are more specifically related to obsolete
|
|
entry processing.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><KBD>o</KBD>
|
|
<DD>
|
|
<A NAME="IDX381"></A>
|
|
Find the next obsolete entry (<CODE>po-next-obsolete-entry</CODE>).
|
|
|
|
<DT><KBD>O</KBD>
|
|
<DD>
|
|
<A NAME="IDX382"></A>
|
|
Find the previous obsolete entry (<CODE>po-previous-obsolete-entry</CODE>).
|
|
|
|
<DT><KBD><KBD>DEL</KBD></KBD>
|
|
<DD>
|
|
<A NAME="IDX383"></A>
|
|
Make an active entry obsolete, or zap out an obsolete entry
|
|
(<CODE>po-fade-out-entry</CODE>).
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="IDX384"></A>
|
|
<A NAME="IDX385"></A>
|
|
<A NAME="IDX386"></A>
|
|
<A NAME="IDX387"></A>
|
|
The commands <KBD>o</KBD> (<CODE>po-next-obsolete-entry</CODE>) and <KBD>O</KBD>
|
|
(<CODE>po-previous-obsolete-entry</CODE>) move forwards or backwards,
|
|
chasing for an obsolete entry. If none is found, the search is
|
|
extended and wraps around in the PO file buffer.
|
|
|
|
</P>
|
|
<P>
|
|
PO mode does not provide ways for un-commenting an obsolete entry
|
|
and making it active, because this would reintroduce an original
|
|
untranslated string which does not correspond to any marked string
|
|
in the program sources. This goes with the philosophy of never
|
|
introducing useless <CODE>msgid</CODE> values.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX388"></A>
|
|
<A NAME="IDX389"></A>
|
|
<A NAME="IDX390"></A>
|
|
<A NAME="IDX391"></A>
|
|
However, it is possible to comment out an active entry, so making
|
|
it obsolete. GNU <CODE>gettext</CODE> utilities will later react to the
|
|
disappearance of a translation by using the untranslated string.
|
|
The command <KBD><KBD>DEL</KBD></KBD> (<CODE>po-fade-out-entry</CODE>) pushes the current entry
|
|
a little further towards annihilation. If the entry is active (it is a
|
|
translated entry), then it is first made fuzzy. If it is already fuzzy,
|
|
then the entry is merely commented out, with confirmation. If the entry
|
|
is already obsolete, then it is completely deleted from the PO file.
|
|
It is easy to recycle the translation so deleted into some other PO file
|
|
entry, usually one which is untranslated. See section <A HREF="gettext_6.html#SEC54">6.6 Modifying Translations</A>.
|
|
|
|
</P>
|
|
<P>
|
|
Here is a quite interesting problem to solve for later development of
|
|
PO mode, for those nights you are not sleepy. The idea would be that
|
|
PO mode might become bright enough, one of these days, to make good
|
|
guesses at retrieving the most probable candidate, among all obsolete
|
|
entries, for initializing the translation of a newly appeared string.
|
|
I think it might be a quite hard problem to do this algorithmically, as
|
|
we have to develop good and efficient measures of string similarity.
|
|
Right now, PO mode completely lets the decision to the translator,
|
|
when the time comes to find the adequate obsolete translation, it
|
|
merely tries to provide handy tools for helping her to do so.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC54" HREF="gettext_toc.html#TOC54">6.6 Modifying Translations</A></H2>
|
|
<P>
|
|
<A NAME="IDX392"></A>
|
|
<A NAME="IDX393"></A>
|
|
|
|
</P>
|
|
<P>
|
|
PO mode prevents direct modification of the PO file, by the usual
|
|
means Emacs gives for altering a buffer's contents. By doing so,
|
|
it pretends helping the translator to avoid little clerical errors
|
|
about the overall file format, or the proper quoting of strings,
|
|
as those errors would be easily made. Other kinds of errors are
|
|
still possible, but some may be caught and diagnosed by the batch
|
|
validation process, which the translator may always trigger by the
|
|
<KBD>V</KBD> command. For all other errors, the translator has to rely on
|
|
her own judgment, and also on the linguistic reports submitted to her
|
|
by the users of the translated package, having the same mother tongue.
|
|
|
|
</P>
|
|
<P>
|
|
When the time comes to create a translation, correct an error diagnosed
|
|
mechanically or reported by a user, the translators have to resort to
|
|
using the following commands for modifying the translations.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><KBD><KBD>RET</KBD></KBD>
|
|
<DD>
|
|
<A NAME="IDX394"></A>
|
|
Interactively edit the translation (<CODE>po-edit-msgstr</CODE>).
|
|
|
|
<DT><KBD><KBD>LFD</KBD></KBD>
|
|
<DD>
|
|
<DT><KBD>C-j</KBD>
|
|
<DD>
|
|
<A NAME="IDX395"></A>
|
|
<A NAME="IDX396"></A>
|
|
Reinitialize the translation with the original, untranslated string
|
|
(<CODE>po-msgid-to-msgstr</CODE>).
|
|
|
|
<DT><KBD>k</KBD>
|
|
<DD>
|
|
<A NAME="IDX397"></A>
|
|
Save the translation on the kill ring, and delete it (<CODE>po-kill-msgstr</CODE>).
|
|
|
|
<DT><KBD>w</KBD>
|
|
<DD>
|
|
<A NAME="IDX398"></A>
|
|
Save the translation on the kill ring, without deleting it
|
|
(<CODE>po-kill-ring-save-msgstr</CODE>).
|
|
|
|
<DT><KBD>y</KBD>
|
|
<DD>
|
|
<A NAME="IDX399"></A>
|
|
Replace the translation, taking the new from the kill ring
|
|
(<CODE>po-yank-msgstr</CODE>).
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="IDX400"></A>
|
|
<A NAME="IDX401"></A>
|
|
The command <KBD><KBD>RET</KBD></KBD> (<CODE>po-edit-msgstr</CODE>) opens a new Emacs
|
|
window meant to edit in a new translation, or to modify an already existing
|
|
translation. The new window contains a copy of the translation taken from
|
|
the current PO file entry, all ready for edition, expunged of all quoting
|
|
marks, fully modifiable and with the complete extent of Emacs modifying
|
|
commands. When the translator is done with her modifications, she may use
|
|
<KBD>C-c C-c</KBD> to close the subedit window with the automatically requoted
|
|
results, or <KBD>C-c C-k</KBD> to abort her modifications. See section <A HREF="gettext_6.html#SEC56">6.8 Details of Sub Edition</A>,
|
|
for more information.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX402"></A>
|
|
<A NAME="IDX403"></A>
|
|
<A NAME="IDX404"></A>
|
|
The command <KBD><KBD>LFD</KBD></KBD> (<CODE>po-msgid-to-msgstr</CODE>) initializes, or
|
|
reinitializes the translation with the original string. This command is
|
|
normally used when the translator wants to redo a fresh translation of
|
|
the original string, disregarding any previous work.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX405"></A>
|
|
It is possible to arrange so, whenever editing an untranslated
|
|
entry, the <KBD><KBD>LFD</KBD></KBD> command be automatically executed. If you set
|
|
<CODE>po-auto-edit-with-msgid</CODE> to <CODE>t</CODE>, the translation gets
|
|
initialised with the original string, in case none exists already.
|
|
The default value for <CODE>po-auto-edit-with-msgid</CODE> is <CODE>nil</CODE>.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX406"></A>
|
|
In fact, whether it is best to start a translation with an empty
|
|
string, or rather with a copy of the original string, is a matter of
|
|
taste or habit. Sometimes, the source language and the
|
|
target language are so different that is simply best to start writing
|
|
on an empty page. At other times, the source and target languages
|
|
are so close that it would be a waste to retype a number of words
|
|
already being written in the original string. A translator may also
|
|
like having the original string right under her eyes, as she will
|
|
progressively overwrite the original text with the translation, even
|
|
if this requires some extra editing work to get rid of the original.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX407"></A>
|
|
<A NAME="IDX408"></A>
|
|
<A NAME="IDX409"></A>
|
|
<A NAME="IDX410"></A>
|
|
<A NAME="IDX411"></A>
|
|
The command <KBD>k</KBD> (<CODE>po-kill-msgstr</CODE>) merely empties the
|
|
translation string, so turning the entry into an untranslated
|
|
one. But while doing so, its previous contents is put apart in
|
|
a special place, known as the kill ring. The command <KBD>w</KBD>
|
|
(<CODE>po-kill-ring-save-msgstr</CODE>) has also the effect of taking a
|
|
copy of the translation onto the kill ring, but it otherwise leaves
|
|
the entry alone, and does <EM>not</EM> remove the translation from the
|
|
entry. Both commands use exactly the Emacs kill ring, which is shared
|
|
between buffers, and which is well known already to Emacs lovers.
|
|
|
|
</P>
|
|
<P>
|
|
The translator may use <KBD>k</KBD> or <KBD>w</KBD> many times in the course
|
|
of her work, as the kill ring may hold several saved translations.
|
|
From the kill ring, strings may later be reinserted in various
|
|
Emacs buffers. In particular, the kill ring may be used for moving
|
|
translation strings between different entries of a single PO file
|
|
buffer, or if the translator is handling many such buffers at once,
|
|
even between PO files.
|
|
|
|
</P>
|
|
<P>
|
|
To facilitate exchanges with buffers which are not in PO mode, the
|
|
translation string put on the kill ring by the <KBD>k</KBD> command is fully
|
|
unquoted before being saved: external quotes are removed, multi-line
|
|
strings are concatenated, and backslash escaped sequences are turned
|
|
into their corresponding characters. In the special case of obsolete
|
|
entries, the translation is also uncommented prior to saving.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX412"></A>
|
|
<A NAME="IDX413"></A>
|
|
The command <KBD>y</KBD> (<CODE>po-yank-msgstr</CODE>) completely replaces the
|
|
translation of the current entry by a string taken from the kill ring.
|
|
Following Emacs terminology, we then say that the replacement
|
|
string is <EM>yanked</EM> into the PO file buffer.
|
|
See section `Yanking' in <CITE>The Emacs Editor</CITE>.
|
|
The first time <KBD>y</KBD> is used, the translation receives the value of
|
|
the most recent addition to the kill ring. If <KBD>y</KBD> is typed once
|
|
again, immediately, without intervening keystrokes, the translation
|
|
just inserted is taken away and replaced by the second most recent
|
|
addition to the kill ring. By repeating <KBD>y</KBD> many times in a row,
|
|
the translator may travel along the kill ring for saved strings,
|
|
until she finds the string she really wanted.
|
|
|
|
</P>
|
|
<P>
|
|
When a string is yanked into a PO file entry, it is fully and
|
|
automatically requoted for complying with the format PO files should
|
|
have. Further, if the entry is obsolete, PO mode then appropriately
|
|
push the inserted string inside comments. Once again, translators
|
|
should not burden themselves with quoting considerations besides, of
|
|
course, the necessity of the translated string itself respective to
|
|
the program using it.
|
|
|
|
</P>
|
|
<P>
|
|
Note that <KBD>k</KBD> or <KBD>w</KBD> are not the only commands pushing strings
|
|
on the kill ring, as almost any PO mode command replacing translation
|
|
strings (or the translator comments) automatically saves the old string
|
|
on the kill ring. The main exceptions to this general rule are the
|
|
yanking commands themselves.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX414"></A>
|
|
To better illustrate the operation of killing and yanking, let's
|
|
use an actual example, taken from a common situation. When the
|
|
programmer slightly modifies some string right in the program, his
|
|
change is later reflected in the PO file by the appearance
|
|
of a new untranslated entry for the modified string, and the fact
|
|
that the entry translating the original or unmodified string becomes
|
|
obsolete. In many cases, the translator might spare herself some work
|
|
by retrieving the unmodified translation from the obsolete entry,
|
|
then initializing the untranslated entry <CODE>msgstr</CODE> field with
|
|
this retrieved translation. Once this done, the obsolete entry is
|
|
not wanted anymore, and may be safely deleted.
|
|
|
|
</P>
|
|
<P>
|
|
When the translator finds an untranslated entry and suspects that a
|
|
slight variant of the translation exists, she immediately uses <KBD>m</KBD>
|
|
to mark the current entry location, then starts chasing obsolete
|
|
entries with <KBD>o</KBD>, hoping to find some translation corresponding
|
|
to the unmodified string. Once found, she uses the <KBD><KBD>DEL</KBD></KBD> command
|
|
for deleting the obsolete entry, knowing that <KBD><KBD>DEL</KBD></KBD> also <EM>kills</EM>
|
|
the translation, that is, pushes the translation on the kill ring.
|
|
Then, <KBD>r</KBD> returns to the initial untranslated entry, and <KBD>y</KBD>
|
|
then <EM>yanks</EM> the saved translation right into the <CODE>msgstr</CODE>
|
|
field. The translator is then free to use <KBD><KBD>RET</KBD></KBD> for fine
|
|
tuning the translation contents, and maybe to later use <KBD>u</KBD>,
|
|
then <KBD>m</KBD> again, for going on with the next untranslated string.
|
|
|
|
</P>
|
|
<P>
|
|
When some sequence of keys has to be typed over and over again, the
|
|
translator may find it useful to become better acquainted with the Emacs
|
|
capability of learning these sequences and playing them back under request.
|
|
See section `Keyboard Macros' in <CITE>The Emacs Editor</CITE>.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC55" HREF="gettext_toc.html#TOC55">6.7 Modifying Comments</A></H2>
|
|
<P>
|
|
<A NAME="IDX415"></A>
|
|
<A NAME="IDX416"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Any translation work done seriously will raise many linguistic
|
|
difficulties, for which decisions have to be made, and the choices
|
|
further documented. These documents may be saved within the
|
|
PO file in form of translator comments, which the translator
|
|
is free to create, delete, or modify at will. These comments may
|
|
be useful to herself when she returns to this PO file after a while.
|
|
|
|
</P>
|
|
<P>
|
|
Comments not having whitespace after the initial <SAMP>`#´</SAMP>, for example,
|
|
those beginning with <SAMP>`#.´</SAMP> or <SAMP>`#:´</SAMP>, are <EM>not</EM> translator
|
|
comments, they are exclusively created by other <CODE>gettext</CODE> tools.
|
|
So, the commands below will never alter such system added comments,
|
|
they are not meant for the translator to modify. See section <A HREF="gettext_2.html#SEC9">2.2 The Format of PO Files</A>.
|
|
|
|
</P>
|
|
<P>
|
|
The following commands are somewhat similar to those modifying translations,
|
|
so the general indications given for those apply here. See section <A HREF="gettext_6.html#SEC54">6.6 Modifying Translations</A>.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><KBD>#</KBD>
|
|
<DD>
|
|
<A NAME="IDX417"></A>
|
|
Interactively edit the translator comments (<CODE>po-edit-comment</CODE>).
|
|
|
|
<DT><KBD>K</KBD>
|
|
<DD>
|
|
<A NAME="IDX418"></A>
|
|
Save the translator comments on the kill ring, and delete it
|
|
(<CODE>po-kill-comment</CODE>).
|
|
|
|
<DT><KBD>W</KBD>
|
|
<DD>
|
|
<A NAME="IDX419"></A>
|
|
Save the translator comments on the kill ring, without deleting it
|
|
(<CODE>po-kill-ring-save-comment</CODE>).
|
|
|
|
<DT><KBD>Y</KBD>
|
|
<DD>
|
|
<A NAME="IDX420"></A>
|
|
Replace the translator comments, taking the new from the kill ring
|
|
(<CODE>po-yank-comment</CODE>).
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
These commands parallel PO mode commands for modifying the translation
|
|
strings, and behave much the same way as they do, except that they handle
|
|
this part of PO file comments meant for translator usage, rather
|
|
than the translation strings. So, if the descriptions given below are
|
|
slightly succinct, it is because the full details have already been given.
|
|
See section <A HREF="gettext_6.html#SEC54">6.6 Modifying Translations</A>.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX421"></A>
|
|
<A NAME="IDX422"></A>
|
|
The command <KBD>#</KBD> (<CODE>po-edit-comment</CODE>) opens a new Emacs window
|
|
containing a copy of the translator comments on the current PO file entry.
|
|
If there are no such comments, PO mode understands that the translator wants
|
|
to add a comment to the entry, and she is presented with an empty screen.
|
|
Comment marks (<CODE>#</CODE>) and the space following them are automatically
|
|
removed before edition, and reinstated after. For translator comments
|
|
pertaining to obsolete entries, the uncommenting and recommenting operations
|
|
are done twice. Once in the editing window, the keys <KBD>C-c C-c</KBD>
|
|
allow the translator to tell she is finished with editing the comment.
|
|
See section <A HREF="gettext_6.html#SEC56">6.8 Details of Sub Edition</A>, for further details.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX423"></A>
|
|
Functions found on <CODE>po-subedit-mode-hook</CODE>, if any, are executed after
|
|
the string has been inserted in the edit buffer.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX424"></A>
|
|
<A NAME="IDX425"></A>
|
|
<A NAME="IDX426"></A>
|
|
<A NAME="IDX427"></A>
|
|
<A NAME="IDX428"></A>
|
|
<A NAME="IDX429"></A>
|
|
The command <KBD>K</KBD> (<CODE>po-kill-comment</CODE>) gets rid of all
|
|
translator comments, while saving those comments on the kill ring.
|
|
The command <KBD>W</KBD> (<CODE>po-kill-ring-save-comment</CODE>) takes
|
|
a copy of the translator comments on the kill ring, but leaves
|
|
them undisturbed in the current entry. The command <KBD>Y</KBD>
|
|
(<CODE>po-yank-comment</CODE>) completely replaces the translator comments
|
|
by a string taken at the front of the kill ring. When this command
|
|
is immediately repeated, the comments just inserted are withdrawn,
|
|
and replaced by other strings taken along the kill ring.
|
|
|
|
</P>
|
|
<P>
|
|
On the kill ring, all strings have the same nature. There is no
|
|
distinction between <EM>translation</EM> strings and <EM>translator
|
|
comments</EM> strings. So, for example, let's presume the translator
|
|
has just finished editing a translation, and wants to create a new
|
|
translator comment to document why the previous translation was
|
|
not good, just to remember what was the problem. Foreseeing that she
|
|
will do that in her documentation, the translator may want to quote
|
|
the previous translation in her translator comments. To do so, she
|
|
may initialize the translator comments with the previous translation,
|
|
still at the head of the kill ring. Because editing already pushed the
|
|
previous translation on the kill ring, she merely has to type <KBD>M-w</KBD>
|
|
prior to <KBD>#</KBD>, and the previous translation will be right there,
|
|
all ready for being introduced by some explanatory text.
|
|
|
|
</P>
|
|
<P>
|
|
On the other hand, presume there are some translator comments already
|
|
and that the translator wants to add to those comments, instead
|
|
of wholly replacing them. Then, she should edit the comment right
|
|
away with <KBD>#</KBD>. Once inside the editing window, she can use the
|
|
regular Emacs commands <KBD>C-y</KBD> (<CODE>yank</CODE>) and <KBD>M-y</KBD>
|
|
(<CODE>yank-pop</CODE>) to get the previous translation where she likes.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC56" HREF="gettext_toc.html#TOC56">6.8 Details of Sub Edition</A></H2>
|
|
<P>
|
|
<A NAME="IDX430"></A>
|
|
|
|
</P>
|
|
<P>
|
|
The PO subedit minor mode has a few peculiarities worth being described
|
|
in fuller detail. It installs a few commands over the usual editing set
|
|
of Emacs, which are described below.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><KBD>C-c C-c</KBD>
|
|
<DD>
|
|
<A NAME="IDX431"></A>
|
|
Complete edition (<CODE>po-subedit-exit</CODE>).
|
|
|
|
<DT><KBD>C-c C-k</KBD>
|
|
<DD>
|
|
<A NAME="IDX432"></A>
|
|
Abort edition (<CODE>po-subedit-abort</CODE>).
|
|
|
|
<DT><KBD>C-c C-a</KBD>
|
|
<DD>
|
|
<A NAME="IDX433"></A>
|
|
Consult auxiliary PO files (<CODE>po-subedit-cycle-auxiliary</CODE>).
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="IDX434"></A>
|
|
<A NAME="IDX435"></A>
|
|
<A NAME="IDX436"></A>
|
|
The window's contents represents a translation for a given message,
|
|
or a translator comment. The translator may modify this window to
|
|
her heart's content. Once this is done, the command <KBD>C-c C-c</KBD>
|
|
(<CODE>po-subedit-exit</CODE>) may be used to return the edited translation into
|
|
the PO file, replacing the original translation, even if it moved out of
|
|
sight or if buffers were switched.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX437"></A>
|
|
<A NAME="IDX438"></A>
|
|
If the translator becomes unsatisfied with her translation or comment,
|
|
to the extent she prefers keeping what was existent prior to the
|
|
<KBD><KBD>RET</KBD></KBD> or <KBD>#</KBD> command, she may use the command <KBD>C-c C-k</KBD>
|
|
(<CODE>po-subedit-abort</CODE>) to merely get rid of edition, while preserving
|
|
the original translation or comment. Another way would be for her to exit
|
|
normally with <KBD>C-c C-c</KBD>, then type <CODE>U</CODE> once for undoing the
|
|
whole effect of last edition.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX439"></A>
|
|
<A NAME="IDX440"></A>
|
|
The command <KBD>C-c C-a</KBD> (<CODE>po-subedit-cycle-auxiliary</CODE>)
|
|
allows for glancing through translations
|
|
already achieved in other languages, directly while editing the current
|
|
translation. This may be quite convenient when the translator is fluent
|
|
at many languages, but of course, only makes sense when such completed
|
|
auxiliary PO files are already available to her (see section <A HREF="gettext_6.html#SEC58">6.10 Consulting Auxiliary PO Files</A>).
|
|
|
|
</P>
|
|
<P>
|
|
Functions found on <CODE>po-subedit-mode-hook</CODE>, if any, are executed after
|
|
the string has been inserted in the edit buffer.
|
|
|
|
</P>
|
|
<P>
|
|
While editing her translation, the translator should pay attention to not
|
|
inserting unwanted <KBD><KBD>RET</KBD></KBD> (newline) characters at the end of
|
|
the translated string if those are not meant to be there, or to removing
|
|
such characters when they are required. Since these characters are not
|
|
visible in the editing buffer, they are easily introduced by mistake.
|
|
To help her, <KBD><KBD>RET</KBD></KBD> automatically puts the character <CODE><</CODE>
|
|
at the end of the string being edited, but this <CODE><</CODE> is not really
|
|
part of the string. On exiting the editing window with <KBD>C-c C-c</KBD>,
|
|
PO mode automatically removes such <KBD><</KBD> and all whitespace added after
|
|
it. If the translator adds characters after the terminating <CODE><</CODE>, it
|
|
looses its delimiting property and integrally becomes part of the string.
|
|
If she removes the delimiting <CODE><</CODE>, then the edited string is taken
|
|
<EM>as is</EM>, with all trailing newlines, even if invisible. Also, if
|
|
the translated string ought to end itself with a genuine <CODE><</CODE>, then
|
|
the delimiting <CODE><</CODE> may not be removed; so the string should appear,
|
|
in the editing window, as ending with two <CODE><</CODE> in a row.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX441"></A>
|
|
When a translation (or a comment) is being edited, the translator may move
|
|
the cursor back into the PO file buffer and freely move to other entries,
|
|
browsing at will. If, with an edition pending, the translator wanders in the
|
|
PO file buffer, she may decide to start modifying another entry. Each entry
|
|
being edited has its own subedit buffer. It is possible to simultaneously
|
|
edit the translation <EM>and</EM> the comment of a single entry, or to
|
|
edit entries in different PO files, all at once. Typing <KBD><KBD>RET</KBD></KBD>
|
|
on a field already being edited merely resumes that particular edit. Yet,
|
|
the translator should better be comfortable at handling many Emacs windows!
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX442"></A>
|
|
Pending subedits may be completed or aborted in any order, regardless
|
|
of how or when they were started. When many subedits are pending and the
|
|
translator asks for quitting the PO file (with the <KBD>q</KBD> command), subedits
|
|
are automatically resumed one at a time, so she may decide for each of them.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC57" HREF="gettext_toc.html#TOC57">6.9 C Sources Context</A></H2>
|
|
<P>
|
|
<A NAME="IDX443"></A>
|
|
<A NAME="IDX444"></A>
|
|
<A NAME="IDX445"></A>
|
|
|
|
</P>
|
|
<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>
|
|
<A NAME="IDX446"></A>
|
|
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>
|
|
<A NAME="IDX447"></A>
|
|
Resume the display of a program source context, or cycle through them
|
|
(<CODE>po-cycle-source-reference</CODE>).
|
|
|
|
<DT><KBD>M-s</KBD>
|
|
<DD>
|
|
<A NAME="IDX448"></A>
|
|
Display of a program source context selected by menu
|
|
(<CODE>po-select-source-reference</CODE>).
|
|
|
|
<DT><KBD>S</KBD>
|
|
<DD>
|
|
<A NAME="IDX449"></A>
|
|
Add a directory to the search path for source files
|
|
(<CODE>po-consider-source-path</CODE>).
|
|
|
|
<DT><KBD>M-S</KBD>
|
|
<DD>
|
|
<A NAME="IDX450"></A>
|
|
Delete a directory from the search path for source files
|
|
(<CODE>po-ignore-source-path</CODE>).
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="IDX451"></A>
|
|
<A NAME="IDX452"></A>
|
|
<A NAME="IDX453"></A>
|
|
<A NAME="IDX454"></A>
|
|
The commands <KBD>s</KBD> (<CODE>po-cycle-source-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 a particular reference among
|
|
many, and displays that reference. It is best used with completion,
|
|
if the translator types <KBD><KBD>TAB</KBD></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>
|
|
<A NAME="IDX455"></A>
|
|
<A NAME="IDX456"></A>
|
|
<A NAME="IDX457"></A>
|
|
<A NAME="IDX458"></A>
|
|
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 <EM>search path</EM> 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="SEC58" HREF="gettext_toc.html#TOC58">6.10 Consulting Auxiliary PO Files</A></H2>
|
|
<P>
|
|
<A NAME="IDX459"></A>
|
|
|
|
</P>
|
|
<P>
|
|
PO mode is able to help the knowledgeable translator, being fluent in
|
|
many languages, at taking advantage of translations already achieved
|
|
in other languages she just happens to know. It provides these other
|
|
language translations as additional context for her own work. Moreover,
|
|
it has features to ease the production of translations for many languages
|
|
at once, for translators preferring to work in this way.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX460"></A>
|
|
<A NAME="IDX461"></A>
|
|
An <EM>auxiliary</EM> PO file is an existing PO file meant for the same
|
|
package the translator is working on, but targeted to a different mother
|
|
tongue language. Commands exist for declaring and handling auxiliary
|
|
PO files, and also for showing contexts for the entry under work.
|
|
|
|
</P>
|
|
<P>
|
|
Here are the auxiliary file commands available in PO mode.
|
|
|
|
</P>
|
|
<DL COMPACT>
|
|
|
|
<DT><KBD>a</KBD>
|
|
<DD>
|
|
<A NAME="IDX462"></A>
|
|
Seek auxiliary files for another translation for the same entry
|
|
(<CODE>po-cycle-auxiliary</CODE>).
|
|
|
|
<DT><KBD>C-c C-a</KBD>
|
|
<DD>
|
|
<A NAME="IDX463"></A>
|
|
Switch to a particular auxiliary file (<CODE>po-select-auxiliary</CODE>).
|
|
|
|
<DT><KBD>A</KBD>
|
|
<DD>
|
|
<A NAME="IDX464"></A>
|
|
Declare this PO file as an auxiliary file (<CODE>po-consider-as-auxiliary</CODE>).
|
|
|
|
<DT><KBD>M-A</KBD>
|
|
<DD>
|
|
<A NAME="IDX465"></A>
|
|
Remove this PO file from the list of auxiliary files
|
|
(<CODE>po-ignore-as-auxiliary</CODE>).
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<A NAME="IDX466"></A>
|
|
<A NAME="IDX467"></A>
|
|
<A NAME="IDX468"></A>
|
|
<A NAME="IDX469"></A>
|
|
Command <KBD>A</KBD> (<CODE>po-consider-as-auxiliary</CODE>) adds the current
|
|
PO file to the list of auxiliary files, while command <KBD>M-A</KBD>
|
|
(<CODE>po-ignore-as-auxiliary</CODE> just removes it.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX470"></A>
|
|
<A NAME="IDX471"></A>
|
|
The command <KBD>a</KBD> (<CODE>po-cycle-auxiliary</CODE>) seeks all auxiliary PO
|
|
files, round-robin, searching for a translated entry in some other language
|
|
having an <CODE>msgid</CODE> field identical as the one for the current entry.
|
|
The found PO file, if any, takes the place of the current PO file in
|
|
the display (its window gets on top). Before doing so, the current PO
|
|
file is also made into an auxiliary file, if not already. So, <KBD>a</KBD>
|
|
in this newly displayed PO file will seek another PO file, and so on,
|
|
so repeating <KBD>a</KBD> will eventually yield back the original PO file.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX472"></A>
|
|
<A NAME="IDX473"></A>
|
|
The command <KBD>C-c C-a</KBD> (<CODE>po-select-auxiliary</CODE>) asks the translator
|
|
for her choice of a particular auxiliary file, with completion, and
|
|
then switches to that selected PO file. The command also checks if
|
|
the selected file has an <CODE>msgid</CODE> field identical as the one for
|
|
the current entry, and if yes, this entry becomes current. Otherwise,
|
|
the cursor of the selected file is left undisturbed.
|
|
|
|
</P>
|
|
<P>
|
|
For all this to work fully, auxiliary PO files will have to be normalized,
|
|
in that way that <CODE>msgid</CODE> fields should be written <EM>exactly</EM>
|
|
the same way. It is possible to write <CODE>msgid</CODE> fields in various
|
|
ways for representing the same string, different writing would break the
|
|
proper behaviour of the auxiliary file commands of PO mode. This is not
|
|
expected to be much a problem in practice, as most existing PO files have
|
|
their <CODE>msgid</CODE> entries written by the same GNU <CODE>gettext</CODE> tools.
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX474"></A>
|
|
However, PO files initially created by PO mode itself, while marking
|
|
strings in source files, are normalised differently. So are PO
|
|
files resulting of the the <SAMP>`M-x normalize´</SAMP> command. Until these
|
|
discrepancies between PO mode and other GNU <CODE>gettext</CODE> tools get
|
|
fully resolved, the translator should stay aware of normalisation issues.
|
|
|
|
</P>
|
|
|
|
|
|
<H2><A NAME="SEC59" HREF="gettext_toc.html#TOC59">6.11 Using Translation Compendia</A></H2>
|
|
<P>
|
|
<A NAME="IDX475"></A>
|
|
|
|
</P>
|
|
<P>
|
|
<A NAME="IDX476"></A>
|
|
A <EM>compendium</EM> is a special PO file containing a set of
|
|
translations recurring in many different packages. The translator can
|
|
use gettext tools to build a new compendium, to add entries to her
|
|
compendium, and to initialize untranslated entries, or to update
|
|
already translated entries, from translations kept in the compendium.
|
|
|
|
</P>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC60" HREF="gettext_toc.html#TOC60">6.11.1 Creating Compendia</A></H3>
|
|
<P>
|
|
<A NAME="IDX477"></A>
|
|
<A NAME="IDX478"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Basically every PO file consisting of translated entries only can be
|
|
declared as a valid compendium. Often the translator wants to have
|
|
special compendia; let's consider two cases: <CITE>concatenating PO
|
|
files</CITE> and <CITE>extracting a message subset from a PO file</CITE>.
|
|
|
|
</P>
|
|
|
|
|
|
<H4><A NAME="SEC61" HREF="gettext_toc.html#TOC61">6.11.1.1 Concatenate PO Files</A></H4>
|
|
|
|
<P>
|
|
<A NAME="IDX479"></A>
|
|
<A NAME="IDX480"></A>
|
|
To concatenate several valid PO files into one compendium file you can
|
|
use <SAMP>`msgcomm´</SAMP> or <SAMP>`msgcat´</SAMP> (the latter preferred):
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
msgcat -o compendium.po file1.po file2.po
|
|
</PRE>
|
|
|
|
<P>
|
|
By default, <CODE>msgcat</CODE> will accumulate divergent translations
|
|
for the same string. Those occurences will be marked as <CODE>fuzzy</CODE>
|
|
and highly visible decorated; calling <CODE>msgcat</CODE> on
|
|
<TT>`file1.po´</TT>:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
#: src/hello.c:200
|
|
#, c-format
|
|
msgid "Report bugs to <%s>.\n"
|
|
msgstr "Comunicar `bugs' a <%s>.\n"
|
|
</PRE>
|
|
|
|
<P>
|
|
and <TT>`file2.po´</TT>:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
#: src/bye.c:100
|
|
#, c-format
|
|
msgid "Report bugs to <%s>.\n"
|
|
msgstr "Comunicar \"bugs\" a <%s>.\n"
|
|
</PRE>
|
|
|
|
<P>
|
|
will result in:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
#: src/hello.c:200 src/bye.c:100
|
|
#, fuzzy, c-format
|
|
msgid "Report bugs to <%s>.\n"
|
|
msgstr ""
|
|
"#-#-#-#-# file1.po #-#-#-#-#\n"
|
|
"Comunicar `bugs' a <%s>.\n"
|
|
"#-#-#-#-# file2.po #-#-#-#-#\n"
|
|
"Comunicar \"bugs\" a <%s>.\n"
|
|
</PRE>
|
|
|
|
<P>
|
|
The translator will have to resolve this "conflict" manually; she
|
|
has to decide whether the first or the second version is appropriate
|
|
(or provide a new translation), to delete the "marker lines", and
|
|
finally to remove the <CODE>fuzzy</CODE> mark.
|
|
|
|
</P>
|
|
<P>
|
|
If the translator knows in advance the first found translation of a
|
|
message is always the best translation she can make use to the
|
|
<SAMP>`--use-first´</SAMP> switch:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
msgcat --use-first -o compendium.po file1.po file2.po
|
|
</PRE>
|
|
|
|
<P>
|
|
A good compendium file must not contain <CODE>fuzzy</CODE> or untranslated
|
|
entries. If input files are "dirty" you must preprocess the input
|
|
files or postprocess the result using <SAMP>`msgattrib --translated --no-fuzzy´</SAMP>.
|
|
|
|
</P>
|
|
|
|
|
|
<H4><A NAME="SEC62" HREF="gettext_toc.html#TOC62">6.11.1.2 Extract a Message Subset from a PO File</A></H4>
|
|
<P>
|
|
<A NAME="IDX481"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Nobody wants to translate the same messages again and again; thus you
|
|
may wish to have a compendium file containing <TT>`getopt.c´</TT> messages.
|
|
|
|
</P>
|
|
<P>
|
|
To extract a message subset (e.g., all <TT>`getopt.c´</TT> messages) from an
|
|
existing PO file into one compendium file you can use <SAMP>`msggrep´</SAMP>:
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
msggrep --location src/getopt.c -o compendium.po file.po
|
|
</PRE>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC63" HREF="gettext_toc.html#TOC63">6.11.2 Using Compendia</A></H3>
|
|
|
|
<P>
|
|
You can use a compendium file to initialize a translation from scratch
|
|
or to update an already existing translation.
|
|
|
|
</P>
|
|
|
|
|
|
<H4><A NAME="SEC64" HREF="gettext_toc.html#TOC64">6.11.2.1 Initialize a New Translation File</A></H4>
|
|
<P>
|
|
<A NAME="IDX482"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Since a PO file with translations does not exist the translator can
|
|
merely use <TT>`/dev/null´</TT> to fake the "old" translation file.
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
msgmerge --compendium compendium.po -o file.po /dev/null file.pot
|
|
</PRE>
|
|
|
|
|
|
|
|
<H4><A NAME="SEC65" HREF="gettext_toc.html#TOC65">6.11.2.2 Update an Existing Translation File</A></H4>
|
|
<P>
|
|
<A NAME="IDX483"></A>
|
|
|
|
</P>
|
|
<P>
|
|
Concatenate the compendium file(s) and the existing PO, merge the
|
|
result with the POT file and remove the obsolete entries (optional,
|
|
here done using <SAMP>`sed´</SAMP>):
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
msgcat --use-first -o update.po compendium1.po compendium2.po file.po
|
|
msgmerge update.po file.pot | sed -e '/^#~/d' > file.po
|
|
</PRE>
|
|
|
|
<P><HR><P>
|
|
Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_5.html">previous</A>, <A HREF="gettext_7.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
|
|
</BODY>
|
|
</HTML>
|