codekingpro/portable-devtools
115k
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>57.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="57.1. For the Translator" /><link rel="next" href="plhandler.html" title="Chapter 58. 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">57.2. For the Programmer</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="nls-translator.html" title="57.1. For the Translator">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="nls.html" title="Chapter 57. Native Language Support">Up</a></td><th width="60%" align="center">Chapter 57. Native Language Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="plhandler.html" title="Chapter 58. 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">57.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">57.2.1. Mechanics</a></span></dt><dt><span class="sect2"><a href="nls-programmer.html#NLS-GUIDELINES">57.2.2. Message-Writing Guidelines</a></span></dt></dl></div><div class="sect2" id="NLS-MECHANICS"><div class="titlepage"><div><div><h3 class="title">57.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 a4 program or library that is part of the5 <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_NLS11#include <locale.h>12#endif13 14...15 16#ifdef ENABLE_NLS17setlocale(LC_ALL, "");18bindtextdomain("<em class="replaceable"><code>progname</code></em>", LOCALEDIR);19textdomain("<em class="replaceable"><code>progname</code></em>");20#endif21</pre><p>22 (The <em class="replaceable"><code>progname</code></em> can actually be chosen23 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">28fprintf(stderr, "panic level %d\n", lvl);29</pre><p>30 would be changed to:31</p><pre class="programlisting">32fprintf(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 is35 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 its42 communication through one or a few functions, such as43 <code class="function">ereport()</code> in the backend. Then you make this44 function call <code class="function">gettext</code> internally on all45 input strings.46 </p></li><li class="step"><p>47 Add a file <code class="filename">nls.mk</code> in the directory with the48 program sources. This file will be read as a makefile. The49 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 the53 <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., those56 marked with <code class="function">gettext</code> or an alternative57 solution. Eventually, this will include nearly all source58 files of the program. If this list gets too long you can59 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 per61 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 translators64 to work on need to know what function calls contain65 translatable strings. By default, only66 <code class="function">gettext()</code> calls are known. If you used67 <code class="function">_</code> or other identifiers you need to list68 them here. If the translatable string is not the first69 argument, the item needs to be of the form70 <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 list77 of provided translations — initially empty.78 </p></li></ol></div><p>79 The build system will automatically take care of building and80 installing the message catalogs.81 </p></div><div class="sect2" id="NLS-GUIDELINES"><div class="titlepage"><div><div><h3 class="title">57.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 easily83 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">88printf("Files were %s.\n", flag ? "copied" : "removed");89</pre><p>90 The word order within the sentence might be different in other91 languages. Also, even if you remember to call <code class="function">gettext()</code> on92 each fragment, the fragments might not translate well separately. It's93 better to duplicate a little code so that each message to be94 translated is a coherent whole. Only numbers, file names, and95 such-like run-time variables should be inserted at run time into96 a message text.97 </p></li><li class="listitem"><p>98 For similar reasons, this won't work:99</p><pre class="programlisting">100printf("copied %d file%s", n, n!=1 ? "s" : "");101</pre><p>102 because it assumes how the plural is formed. If you figured you103 could solve it like this:104</p><pre class="programlisting">105if (n==1)106 printf("copied 1 file");107else108 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 message112 to avoid the issue altogether, for instance like this:113</p><pre class="programlisting">114printf("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 generating119 a primary or detail error message in <code class="function">ereport()</code>, you can120 write something like this:121</p><pre class="programlisting">122errmsg_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 English128 singular form, the second is the format string appropriate for129 English plural form, and the third is the integer control value130 that determines which plural form to use. Subsequent arguments131 are formatted per the format string as usual. (Normally, the132 pluralization control value will also be one of the values to be133 formatted, so it has to be written twice.) In English it only134 matters whether <em class="replaceable"><code>n</code></em> is 1 or not 1, but in other135 languages there can be many different plural forms. The translator136 sees the two English forms as a group and has the opportunity to137 supply multiple substitute strings, with the appropriate one being138 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 an141 <code class="function">errmsg</code> or <code class="function">errdetail</code> report, you have to use142 the underlying function <code class="function">ngettext</code>. See the gettext143 documentation.144 </p></li><li class="listitem"><p>145 If you want to communicate something to the translator, such as146 about how a message is intended to line up with other output,147 precede the occurrence of the string with a comment that starts148 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 that153 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="57.1. For the Translator">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="nls.html" title="Chapter 57. Native Language Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plhandler.html" title="Chapter 58. Writing a Procedural Language Handler">Next</a></td></tr><tr><td width="40%" align="left" valign="top">57.1. For the Translator </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 58. Writing a Procedural Language Handler</td></tr></table></div></body></html>