begriffs open source - ai-pg/blob - full-docs/src/sgml/html/nls-programmer.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>56.2. For the Programmer</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="nls-translator.html" title="56.1. For the Translator" /><link rel="next" href="plhandler.html" title="Chapter 57. Writing a Procedural Language Handler" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">56.2. For the Programmer</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="nls-translator.html" title="56.1. For the Translator">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="nls.html" title="Chapter 56. Native Language Support">Up</a></td><th width="60%" align="center">Chapter 56. Native Language Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plhandler.html" title="Chapter 57. Writing a Procedural Language Handler">Next</a></td></tr></table><hr /></div><div class="sect1" id="NLS-PROGRAMMER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">56.2. For the Programmer <a href="#NLS-PROGRAMMER" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="nls-programmer.html#NLS-MECHANICS">56.2.1. Mechanics</a></span></dt><dt><span class="sect2"><a href="nls-programmer.html#NLS-GUIDELINES">56.2.2. Message-Writing Guidelines</a></span></dt></dl></div><div class="sect2" id="NLS-MECHANICS"><div class="titlepage"><div><div><h3 class="title">56.2.1. Mechanics <a href="#NLS-MECHANICS" class="id_link">#</a></h3></div></div></div><p>
   3    This section describes how to implement native language support in a
   4    program or library that is part of the
   5    <span class="productname">PostgreSQL</span> distribution.
   6    Currently, it only applies to C programs.
   7   </p><div class="procedure" id="id-1.10.8.3.2.3"><p class="title"><strong>Adding NLS Support to a Program</strong></p><ol class="procedure" type="1"><li class="step"><p>
   8      Insert this code into the start-up sequence of the program:
   9 </p><pre class="programlisting">
  10 #ifdef ENABLE_NLS
  11 #include &lt;locale.h&gt;
  12 #endif
  13
  14 ...
  15
  16 #ifdef ENABLE_NLS
  17 setlocale(LC_ALL, "");
  18 bindtextdomain("<em class="replaceable"><code>progname</code></em>", LOCALEDIR);
  19 textdomain("<em class="replaceable"><code>progname</code></em>");
  20 #endif
  21 </pre><p>
  22      (The <em class="replaceable"><code>progname</code></em> can actually be chosen
  23      freely.)
  24     </p></li><li class="step"><p>
  25      Wherever a message that is a candidate for translation is found,
  26      a call to <code class="function">gettext()</code> needs to be inserted.  E.g.:
  27 </p><pre class="programlisting">
  28 fprintf(stderr, "panic level %d\n", lvl);
  29 </pre><p>
  30      would be changed to:
  31 </p><pre class="programlisting">
  32 fprintf(stderr, gettext("panic level %d\n"), lvl);
  33 </pre><p>
  34      (<code class="symbol">gettext</code> is defined as a no-op if NLS support is
  35      not configured.)
  36     </p><p>
  37      This tends to add a lot of clutter.  One common shortcut is to use:
  38 </p><pre class="programlisting">
  39 #define _(x) gettext(x)
  40 </pre><p>
  41      Another solution is feasible if the program does much of its
  42      communication through one or a few functions, such as
  43      <code class="function">ereport()</code> in the backend.  Then you make this
  44      function call <code class="function">gettext</code> internally on all
  45      input strings.
  46     </p></li><li class="step"><p>
  47      Add a file <code class="filename">nls.mk</code> in the directory with the
  48      program sources.  This file will be read as a makefile.  The
  49      following variable assignments need to be made here:
  50
  51      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="varname">CATALOG_NAME</code></span></dt><dd><p>
  52          The program name, as provided in the
  53          <code class="function">textdomain()</code> call.
  54         </p></dd><dt><span class="term"><code class="varname">GETTEXT_FILES</code></span></dt><dd><p>
  55          List of files that contain translatable strings, i.e., those
  56          marked with <code class="function">gettext</code> or an alternative
  57          solution.  Eventually, this will include nearly all source
  58          files of the program.  If this list gets too long you can
  59          make the first <span class="quote">“<span class="quote">file</span>”</span> be a <code class="literal">+</code>
  60          and the second word be a file that contains one file name per
  61          line.
  62         </p></dd><dt><span class="term"><code class="varname">GETTEXT_TRIGGERS</code></span></dt><dd><p>
  63          The tools that generate message catalogs for the translators
  64          to work on need to know what function calls contain
  65          translatable strings.  By default, only
  66          <code class="function">gettext()</code> calls are known.  If you used
  67          <code class="function">_</code> or other identifiers you need to list
  68          them here.  If the translatable string is not the first
  69          argument, the item needs to be of the form
  70          <code class="literal">func:2</code> (for the second argument).
  71          If you have a function that supports pluralized messages,
  72          the item should look like <code class="literal">func:1,2</code>
  73          (identifying the singular and plural message arguments).
  74         </p></dd></dl></div><p>
  75     </p></li><li class="step"><p>
  76      Add a file <code class="filename">po/LINGUAS</code>, which will contain the list
  77      of provided translations — initially empty.
  78     </p></li></ol></div><p>
  79    The build system will automatically take care of building and
  80    installing the message catalogs.
  81   </p></div><div class="sect2" id="NLS-GUIDELINES"><div class="titlepage"><div><div><h3 class="title">56.2.2. Message-Writing Guidelines <a href="#NLS-GUIDELINES" class="id_link">#</a></h3></div></div></div><p>
  82    Here are some guidelines for writing messages that are easily
  83    translatable.
  84
  85    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  86       Do not construct sentences at run-time, like:
  87 </p><pre class="programlisting">
  88 printf("Files were %s.\n", flag ? "copied" : "removed");
  89 </pre><p>
  90       The word order within the sentence might be different in other
  91       languages.  Also, even if you remember to call <code class="function">gettext()</code> on
  92       each fragment, the fragments might not translate well separately.  It's
  93       better to duplicate a little code so that each message to be
  94       translated is a coherent whole.  Only numbers, file names, and
  95       such-like run-time variables should be inserted at run time into
  96       a message text.
  97      </p></li><li class="listitem"><p>
  98       For similar reasons, this won't work:
  99 </p><pre class="programlisting">
 100 printf("copied %d file%s", n, n!=1 ? "s" : "");
 101 </pre><p>
 102       because it assumes how the plural is formed.  If you figured you
 103       could solve it like this:
 104 </p><pre class="programlisting">
 105 if (n==1)
 106     printf("copied 1 file");
 107 else
 108     printf("copied %d files", n):
 109 </pre><p>
 110       then be disappointed.  Some languages have more than two forms,
 111       with some peculiar rules.  It's often best to design the message
 112       to avoid the issue altogether, for instance like this:
 113 </p><pre class="programlisting">
 114 printf("number of copied files: %d", n);
 115 </pre><p>
 116      </p><p>
 117       If you really want to construct a properly pluralized message,
 118       there is support for this, but it's a bit awkward.  When generating
 119       a primary or detail error message in <code class="function">ereport()</code>, you can
 120       write something like this:
 121 </p><pre class="programlisting">
 122 errmsg_plural("copied %d file",
 123               "copied %d files",
 124               n,
 125               n)
 126 </pre><p>
 127       The first argument is the format string appropriate for English
 128       singular form, the second is the format string appropriate for
 129       English plural form, and the third is the integer control value
 130       that determines which plural form to use.  Subsequent arguments
 131       are formatted per the format string as usual.  (Normally, the
 132       pluralization control value will also be one of the values to be
 133       formatted, so it has to be written twice.)  In English it only
 134       matters whether <em class="replaceable"><code>n</code></em> is 1 or not 1, but in other
 135       languages there can be many different plural forms.  The translator
 136       sees the two English forms as a group and has the opportunity to
 137       supply multiple substitute strings, with the appropriate one being
 138       selected based on the run-time value of <em class="replaceable"><code>n</code></em>.
 139      </p><p>
 140       If you need to pluralize a message that isn't going directly to an
 141       <code class="function">errmsg</code> or <code class="function">errdetail</code> report, you have to use
 142       the underlying function <code class="function">ngettext</code>.  See the gettext
 143       documentation.
 144      </p></li><li class="listitem"><p>
 145       If you want to communicate something to the translator, such as
 146       about how a message is intended to line up with other output,
 147       precede the occurrence of the string with a comment that starts
 148       with <code class="literal">translator</code>, e.g.:
 149 </p><pre class="programlisting">
 150 /* translator: This message is not what it seems to be. */
 151 </pre><p>
 152       These comments are copied to the message catalog files so that
 153       the translators can see them.
 154      </p></li></ul></div><p>
 155   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="nls-translator.html" title="56.1. For the Translator">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="nls.html" title="Chapter 56. Native Language Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plhandler.html" title="Chapter 57. Writing a Procedural Language Handler">Next</a></td></tr><tr><td width="40%" align="left" valign="top">56.1. For the Translator </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 57. Writing a Procedural Language Handler</td></tr></table></div></body></html>