-<!--
-$PostgreSQL: pgsql/doc/src/sgml/nls.sgml,v 1.12 2005/04/09 03:52:43 momjian Exp $
--->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/nls.sgml,v 1.18 2009/06/04 18:33:06 tgl Exp $ -->
<chapter id="nls">
<chapterinfo>
<filename>msgmerge</filename>, respectively, in a GNU-compatible
implementation. Later, we will try to arrange it so that if you
use a packaged source distribution, you won't need
- <filename>xgettext</filename>. (From CVS, you will still need
+ <filename>xgettext</filename>. (If working from CVS, you will still need
it.) <application>GNU Gettext 0.10.36</application> or later is currently recommended.
</para>
<para>
The # character introduces a comment. If whitespace immediately
follows the # character, then this is a comment maintained by the
- translator. There may also be automatic comments, which have a
+ translator. There can also be automatic comments, which have a
non-whitespace character immediately following the #. These are
maintained by the various tools that operate on the PO files and
are intended to aid the translator.
If there are already some <filename>.po</filename> files, then
someone has already done some translation work. The files are
named <filename><replaceable>language</replaceable>.po</filename>,
- where <replaceable>language</replaceable> is the
+ where <replaceable>language</replaceable> is the
<ulink url="http://lcweb.loc.gov/standards/iso639-2/englangn.html">
ISO 639-1 two-letter language code (in lower case)</ulink>, e.g.,
<filename>fr.po</filename> for French. If there is really a need
for more than one translation effort per language then the files
- may also be named
+ can also be named
<filename><replaceable>language</replaceable>_<replaceable>region</replaceable>.po</filename>
where <replaceable>region</replaceable> is the
<ulink url="http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/en_listp1.html">
<para>
If you need to start a new translation effort, then first run the
- command
+ command:
<programlisting>
gmake init-po
</programlisting>
<programlisting>
AVAIL_LANGUAGES := de fr
</programlisting>
- (Other languages may appear, of course.)
+ (Other languages can appear, of course.)
</para>
<para>
- As the underlying program or library changes, messages may be
+ As the underlying program or library changes, messages might be
changed or added by the programmers. In this case you do not need
- to start from scratch. Instead, run the command
+ to start from scratch. Instead, run the command:
<programlisting>
gmake update-po
</programlisting>
which will create a new blank message catalog file (the pot file
you started with) and will merge it with the existing PO files.
If the merge algorithm is not sure about a particular message it
- marks it <quote>fuzzy</quote> as explained above. For the case
- where something went really wrong, the old PO file is saved with a
- <filename>.po.old</filename> extension.
+ marks it <quote>fuzzy</quote> as explained above. The new PO file
+ is saved with a <filename>.po.new</filename> extension.
</para>
</sect2>
<para>
The PO files can be edited with a regular text editor. The
translator should only change the area between the quotes after
- the msgstr directive, may add comments and alter the fuzzy flag.
+ the msgstr directive, add comments, and alter the fuzzy flag.
There is (unsurprisingly) a PO mode for Emacs, which I find quite
useful.
</para>
that gives room for other people to pick up your work. However,
you are encouraged to give priority to removing fuzzy entries
after doing a merge. Remember that fuzzy entries will not be
- installed; they only serve as reference what might be the right
+ installed; they only serve as reference for what might be the right
translation.
</para>
<literal><replaceable>digits</replaceable>$</literal> needs to
follow the % immediately, before any other format manipulators.
(This feature really exists in the <function>printf</function>
- family of functions. You may not have heard of it before because
+ family of functions. You might not have heard of it before because
there is little use for it outside of message
internationalization.)
</para>
normally. The corrected string can be merged in when the
program sources have been updated. If the original string
contains a factual mistake, report that (or fix it yourself)
- and do not translate it. Instead, you may mark the string with
+ and do not translate it. Instead, you can mark the string with
a comment in the PO file.
</para>
</listitem>
open file %s</literal>) should probably not start with a
capital letter (if your language distinguishes letter case) or
end with a period (if your language uses punctuation marks).
- It may help to read <xref linkend="error-style-guide">.
+ It might help to read <xref linkend="error-style-guide">.
</para>
</listitem>
<step>
<para>
Wherever a message that is a candidate for translation is found,
- a call to <function>gettext()</function> needs to be inserted. E.g.,
+ a call to <function>gettext()</function> needs to be inserted. E.g.:
<programlisting>
fprintf(stderr, "panic level %d\n", lvl);
</programlisting>
- would be changed to
+ would be changed to:
<programlisting>
fprintf(stderr, gettext("panic level %d\n"), lvl);
</programlisting>
- (<symbol>gettext</symbol> is defined as a no-op if no NLS is
- configured.)
+ (<symbol>gettext</symbol> is defined as a no-op if NLS support is
+ not configured.)
</para>
<para>
- This may tend to add a lot of clutter. One common shortcut is to use
+ This tends to add a lot of clutter. One common shortcut is to use:
<programlisting>
#define _(x) gettext(x)
</programlisting>
them here. If the translatable string is not the first
argument, the item needs to be of the form
<literal>func:2</literal> (for the second argument).
+ If you have a function that supports pluralized messages,
+ the item should look like <literal>func:1,2</literal>
+ (identifying the singular and plural message arguments).
</para>
</listitem>
</varlistentry>
<itemizedlist>
<listitem>
<para>
- Do not construct sentences at run-time, like
+ Do not construct sentences at run-time, like:
<programlisting>
printf("Files were %s.\n", flag ? "copied" : "removed");
</programlisting>
- The word order within the sentence may be different in other
- languages. Also, even if you remember to call gettext() on each
- fragment, the fragments may not translate well separately. It's
+ The word order within the sentence might be different in other
+ languages. Also, even if you remember to call <function>gettext()</> on
+ each fragment, the fragments might not translate well separately. It's
better to duplicate a little code so that each message to be
translated is a coherent whole. Only numbers, file names, and
- such-like run-time variables should be inserted at runtime into
+ such-like run-time variables should be inserted at run time into
a message text.
</para>
</listitem>
printf("copied %d file%s", n, n!=1 ? "s" : "");
</programlisting>
because it assumes how the plural is formed. If you figured you
- could solve it like this
+ could solve it like this:
<programlisting>
if (n==1)
printf("copied 1 file");
printf("copied %d files", n):
</programlisting>
then be disappointed. Some languages have more than two forms,
- with some peculiar rules. We may have a solution for this in
- the future, but for now the matter is best avoided altogether.
- You could write:
+ with some peculiar rules. It's often best to design the message
+ to avoid the issue altogether, for instance like this:
<programlisting>
printf("number of copied files: %d", n);
</programlisting>
</para>
+
+ <para>
+ If you really want to construct a properly pluralized message,
+ there is support for this, but it's a bit awkward. When generating
+ a primary or detail error message in <function>ereport()</>, you can
+ write something like this:
+<programlisting>
+errmsg_plural("copied %d file",
+ "copied %d files",
+ n,
+ n)
+</programlisting>
+ The first argument is the format string appropriate for English
+ singular form, the second is the format string appropriate for
+ English plural form, and the third is the integer control value
+ that determines which plural form to use. Subsequent arguments
+ are formatted per the format string as usual. (Normally, the
+ pluralization control value will also be one of the values to be
+ formatted, so it has to be written twice.) In English it only
+ matters whether <replaceable>n</> is 1 or not 1, but in other
+ languages there can be many different plural forms. The translator
+ sees the two English forms as a group and has the opportunity to
+ supply multiple substitute strings, with the appropriate one being
+ selected based on the run-time value of <replaceable>n</>.
+ </para>
+
+ <para>
+ If you need to pluralize a message that isn't going directly to an
+ <function>errmsg</> or <function>errdetail</> report, you have to use
+ the underlying function <function>ngettext</>. See the gettext
+ documentation.
+ </para>
</listitem>
<listitem>
If you want to communicate something to the translator, such as
about how a message is intended to line up with other output,
precede the occurrence of the string with a comment that starts
- with <literal>translator</literal>, e.g.,
+ with <literal>translator</literal>, e.g.:
<programlisting>
/* translator: This message is not what it seems to be. */
</programlisting>
projects / postgresql / blobdiff