nls.sgml

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

       argument from the list.  The
       <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
       there is little use for it outside of message
       internationalization.)
      </para>
     </listitem>

     <listitem>
      <para>
       If the original string contains a linguistic mistake, report
       that (or fix it yourself in the program source) and translate
       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
       a comment in the PO file.
      </para>
     </listitem>

     <listitem>
      <para>
       Maintain the style and tone of the original string.
       Specifically, messages that are not sentences (<literal>cannot
       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">.
      </para>
     </listitem>

     <listitem>
      <para>
       If you don't know what a message means, or if it is ambiguous,
       ask on the developers' mailing list.  Chances are that English
       speaking end users might also not understand it or find it
       ambiguous, so it's best to improve the message.
      </para>
     </listitem>

    </itemizedlist>
   </para>
  </sect2>

 </sect1>


 <sect1 id="nls-programmer">
  <title>For the Programmer</title>

  <sect2 id="nls-mechanics">
   <title>Mechanics</title>

  <para>
   This section describes how to implement native language support in a
   program or library that is part of the
   <productname>PostgreSQL</> distribution.
   Currently, it only applies to C programs.
  </para>

  <procedure>
   <title>Adding NLS support to a program</title>

   <step>
    <para>
     Insert this code into the start-up sequence of the program:
<programlisting>
#ifdef ENABLE_NLS
#include &lt;locale.h&gt;
#endif

...

#ifdef ENABLE_NLS
setlocale(LC_ALL, "");
bindtextdomain("<replaceable>progname</replaceable>", LOCALEDIR);
textdomain("<replaceable>progname</replaceable>");
#endif
</programlisting>
     (The <replaceable>progname</replaceable> can actually be chosen
     freely.)
    </para>
   </step>

   <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.,
<programlisting>
fprintf(stderr, "panic level %d\n", lvl);
</programlisting>
     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.)
    </para>

    <para>
     This may tend to add a lot of clutter.  One common shortcut is to use
<programlisting>
#define _(x) gettext(x)
</programlisting>
     Another solution is feasible if the program does much of its
     communication through one or a few functions, such as
     <function>ereport()</function> in the backend.  Then you make this
     function call <function>gettext</function> internally on all
     input strings.
    </para>
   </step>

   <step>
    <para>
     Add a file <filename>nls.mk</filename> in the directory with the
     program sources.  This file will be read as a makefile.  The
     following variable assignments need to be made here:

     <variablelist>
      <varlistentry>
       <term><varname>CATALOG_NAME</varname></term>

       <listitem>
        <para>
         The program name, as provided in the
         <function>textdomain()</function> call.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><varname>AVAIL_LANGUAGES</varname></term>

       <listitem>
        <para>
         List of provided translations &mdash; initially empty.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><varname>GETTEXT_FILES</varname></term>

       <listitem>
        <para>
         List of files that contain translatable strings, i.e., those
         marked with <function>gettext</function> or an alternative
         solution.  Eventually, this will include nearly all source
         files of the program.  If this list gets too long you can
         make the first <quote>file</quote> be a <literal>+</literal>
         and the second word be a file that contains one file name per
         line.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><varname>GETTEXT_TRIGGERS</varname></term>

       <listitem>
        <para>
         The tools that generate message catalogs for the translators
         to work on need to know what function calls contain
         translatable strings.  By default, only
         <function>gettext()</function> calls are known.  If you used
         <function>_</function> or other identifiers you need to list
         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).
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
   </step>

  </procedure>

  <para>
   The build system will automatically take care of building and
   installing the message catalogs.
  </para>
  </sect2>

  <sect2 id="nls-guidelines">
   <title>Message-writing guidelines</title>

  <para>
   Here are some guidelines for writing messages that are easily
   translatable.

   <itemizedlist>
    <listitem>
     <para>
      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
      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 run time into
      a message text.
     </para>
    </listitem>

    <listitem>
     <para>
      For similar reasons, this won't work:
<programlisting>
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
<programlisting>
if (n==1)
    printf("copied 1 file");
else
    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:
<programlisting>
printf("number of copied files: %d", n);
</programlisting>
     </para>
    </listitem>

    <listitem>
     <para>
      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.,
<programlisting>
/* translator: This message is not what it seems to be. */
</programlisting>
      These comments are copied to the message catalog files so that
      the translators can see them.
     </para>
    </listitem>
   </itemizedlist>
  </para>
  </sect2>
 </sect1>

</chapter>