~ubuntu-branches/ubuntu/trusty/postgresql-9.3/trusty-updates : contents of doc/src/sgml/html/nls-programmer.html at revision 27

~ubuntu-branches/ubuntu/trusty/postgresql-9.3/trusty-updates : (revision 27)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>For the Programmer</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.3.13 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Native Language Support"
HREF="nls.html"><LINK
REL="PREVIOUS"
TITLE="For the Translator"
HREF="nls-translator.html"><LINK
REL="NEXT"
TITLE="Writing A Procedural Language Handler"
HREF="plhandler.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2016-05-09T21:13:26"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.3.13 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="For the Translator"
HREF="nls-translator.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="nls.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 50. Native Language Support</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Writing A Procedural Language Handler"
HREF="plhandler.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="NLS-PROGRAMMER"
>50.2. For the Programmer</A
></H1
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="NLS-MECHANICS"
>50.2.1. Mechanics</A
></H2
><P
>   This section describes how to implement native language support in a
   program or library that is part of the
   <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> distribution.
   Currently, it only applies to C programs.
  </P
><DIV
CLASS="PROCEDURE"
><P
><B
>Adding NLS Support to a Program</B
></P
><OL
TYPE="1"
><LI
CLASS="STEP"
><P
>     Insert this code into the start-up sequence of the program:
</P><PRE
CLASS="PROGRAMLISTING"
>#ifdef ENABLE_NLS
#include &lt;locale.h&gt;
#endif

...

#ifdef ENABLE_NLS
setlocale(LC_ALL, "");
bindtextdomain("<TT
CLASS="REPLACEABLE"
><I
>progname</I
></TT
>", LOCALEDIR);
textdomain("<TT
CLASS="REPLACEABLE"
><I
>progname</I
></TT
>");
#endif</PRE
><P>
     (The <TT
CLASS="REPLACEABLE"
><I
>progname</I
></TT
> can actually be chosen
     freely.)
    </P
></LI
><LI
CLASS="STEP"
><P
>     Wherever a message that is a candidate for translation is found,
     a call to <CODE
CLASS="FUNCTION"
>gettext()</CODE
> needs to be inserted.  E.g.:
</P><PRE
CLASS="PROGRAMLISTING"
>fprintf(stderr, "panic level %d\n", lvl);</PRE
><P>
     would be changed to:
</P><PRE
CLASS="PROGRAMLISTING"
>fprintf(stderr, gettext("panic level %d\n"), lvl);</PRE
><P>
     (<TT
CLASS="SYMBOL"
>gettext</TT
> is defined as a no-op if NLS support is
     not configured.)
    </P
><P
>     This tends to add a lot of clutter.  One common shortcut is to use:
</P><PRE
CLASS="PROGRAMLISTING"
>#define _(x) gettext(x)</PRE
><P>
     Another solution is feasible if the program does much of its
     communication through one or a few functions, such as
     <CODE
CLASS="FUNCTION"
>ereport()</CODE
> in the backend.  Then you make this
     function call <CODE
CLASS="FUNCTION"
>gettext</CODE
> internally on all
     input strings.
    </P
></LI
><LI
CLASS="STEP"
><P
>     Add a file <TT
CLASS="FILENAME"
>nls.mk</TT
> in the directory with the
     program sources.  This file will be read as a makefile.  The
     following variable assignments need to be made here:

     <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="VARNAME"
>CATALOG_NAME</TT
></DT
><DD
><P
>         The program name, as provided in the
         <CODE
CLASS="FUNCTION"
>textdomain()</CODE
> call.
        </P
></DD
><DT
><TT
CLASS="VARNAME"
>AVAIL_LANGUAGES</TT
></DT
><DD
><P
>         List of provided translations &mdash; initially empty.
        </P
></DD
><DT
><TT
CLASS="VARNAME"
>GETTEXT_FILES</TT
></DT
><DD
><P
>         List of files that contain translatable strings, i.e., those
         marked with <CODE
CLASS="FUNCTION"
>gettext</CODE
> 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 <SPAN
CLASS="QUOTE"
>"file"</SPAN
> be a <TT
CLASS="LITERAL"
>+</TT
>
         and the second word be a file that contains one file name per
         line.
        </P
></DD
><DT
><TT
CLASS="VARNAME"
>GETTEXT_TRIGGERS</TT
></DT
><DD
><P
>         The tools that generate message catalogs for the translators
         to work on need to know what function calls contain
         translatable strings.  By default, only
         <CODE
CLASS="FUNCTION"
>gettext()</CODE
> calls are known.  If you used
         <CODE
CLASS="FUNCTION"
>_</CODE
> 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
         <TT
CLASS="LITERAL"
>func:2</TT
> (for the second argument).
         If you have a function that supports pluralized messages,
         the item should look like <TT
CLASS="LITERAL"
>func:1,2</TT
>
         (identifying the singular and plural message arguments).
        </P
></DD
></DL
></DIV
><P>
    </P
></LI
></OL
></DIV
><P
>   The build system will automatically take care of building and
   installing the message catalogs.
  </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="NLS-GUIDELINES"
>50.2.2. Message-writing Guidelines</A
></H2
><P
>   Here are some guidelines for writing messages that are easily
   translatable.

   <P
></P
></P><UL
><LI
><P
>      Do not construct sentences at run-time, like:
</P><PRE
CLASS="PROGRAMLISTING"
>printf("Files were %s.\n", flag ? "copied" : "removed");</PRE
><P>
      The word order within the sentence might be different in other
      languages.  Also, even if you remember to call <CODE
CLASS="FUNCTION"
>gettext()</CODE
> 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 run time into
      a message text.
     </P
></LI
><LI
><P
>      For similar reasons, this won't work:
</P><PRE
CLASS="PROGRAMLISTING"
>printf("copied %d file%s", n, n!=1 ? "s" : "");</PRE
><P>
      because it assumes how the plural is formed.  If you figured you
      could solve it like this:
</P><PRE
CLASS="PROGRAMLISTING"
>if (n==1)
    printf("copied 1 file");
else
    printf("copied %d files", n):</PRE
><P>
      then be disappointed.  Some languages have more than two forms,
      with some peculiar rules.  It's often best to design the message
      to avoid the issue altogether, for instance like this:
</P><PRE
CLASS="PROGRAMLISTING"
>printf("number of copied files: %d", n);</PRE
><P>
     </P
><P
>      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 <CODE
CLASS="FUNCTION"
>ereport()</CODE
>, you can
      write something like this:
</P><PRE
CLASS="PROGRAMLISTING"
>errmsg_plural("copied %d file",
              "copied %d files",
              n,
              n)</PRE
><P>
      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 <TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
> 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 <TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
>.
     </P
><P
>      If you need to pluralize a message that isn't going directly to an
      <CODE
CLASS="FUNCTION"
>errmsg</CODE
> or <CODE
CLASS="FUNCTION"
>errdetail</CODE
> report, you have to use
      the underlying function <CODE
CLASS="FUNCTION"
>ngettext</CODE
>.  See the gettext
      documentation.
     </P
></LI
><LI
><P
>      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 <TT
CLASS="LITERAL"
>translator</TT
>, e.g.:
</P><PRE
CLASS="PROGRAMLISTING"
>/* translator: This message is not what it seems to be. */</PRE
><P>
      These comments are copied to the message catalog files so that
      the translators can see them.
     </P
></LI
></UL
><P>
  </P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="nls-translator.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="plhandler.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>For the Translator</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="nls.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Writing A Procedural Language Handler</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>