I386LINUX/util/I386LINUX/doc/postgresql/html/nls-programmer.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >For the Programmer</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REV="MADE"
  10 HREF="mailto:pgsql-docs@postgresql.org"><LINK
  11 REL="HOME"
  12 TITLE="PostgreSQL 7.4.1 Documentation"
  13 HREF="index.html"><LINK
  14 REL="UP"
  15 TITLE="Native Language Support"
  16 HREF="nls.html"><LINK
  17 REL="PREVIOUS"
  18 TITLE="Native Language Support"
  19 HREF="nls.html"><LINK
  20 REL="NEXT"
  21 TITLE="Writing A Procedural Language Handler"
  22 HREF="plhandler.html"><LINK
  23 REL="STYLESHEET"
  24 TYPE="text/css"
  25 HREF="stylesheet.css"><META
  26 NAME="creation"
  27 CONTENT="2003-12-22T03:48:47"></HEAD
  28 ><BODY
  29 CLASS="SECT1"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 SUMMARY="Header navigation table"
  34 WIDTH="100%"
  35 BORDER="0"
  36 CELLPADDING="0"
  37 CELLSPACING="0"
  38 ><TR
  39 ><TH
  40 COLSPAN="5"
  41 ALIGN="center"
  42 VALIGN="bottom"
  43 >PostgreSQL 7.4.1 Documentation</TH
  44 ></TR
  45 ><TR
  46 ><TD
  47 WIDTH="10%"
  48 ALIGN="left"
  49 VALIGN="top"
  50 ><A
  51 HREF="nls.html"
  52 ACCESSKEY="P"
  53 >Prev</A
  54 ></TD
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="top"
  59 ><A
  60 HREF="nls.html"
  61 >Fast Backward</A
  62 ></TD
  63 ><TD
  64 WIDTH="60%"
  65 ALIGN="center"
  66 VALIGN="bottom"
  67 >Chapter 46. Native Language Support</TD
  68 ><TD
  69 WIDTH="10%"
  70 ALIGN="right"
  71 VALIGN="top"
  72 ><A
  73 HREF="nls.html"
  74 >Fast Forward</A
  75 ></TD
  76 ><TD
  77 WIDTH="10%"
  78 ALIGN="right"
  79 VALIGN="top"
  80 ><A
  81 HREF="plhandler.html"
  82 ACCESSKEY="N"
  83 >Next</A
  84 ></TD
  85 ></TR
  86 ></TABLE
  87 ><HR
  88 ALIGN="LEFT"
  89 WIDTH="100%"></DIV
  90 ><DIV
  91 CLASS="SECT1"
  92 ><H1
  93 CLASS="SECT1"
  94 ><A
  95 NAME="NLS-PROGRAMMER"
  96 >46.2. For the Programmer</A
  97 ></H1
  98 ><DIV
  99 CLASS="SECT2"
 100 ><H2
 101 CLASS="SECT2"
 102 ><A
 103 NAME="NLS-MECHANICS"
 104 >46.2.1. Mechanics</A
 105 ></H2
 106 ><P
 107 >   This section describes how to implement native language support in a
 108    program or library that is part of the
 109    <SPAN
 110 CLASS="PRODUCTNAME"
 111 >PostgreSQL</SPAN
 112 > distribution.
 113    Currently, it only applies to C programs.
 114   </P
 115 ><DIV
 116 CLASS="PROCEDURE"
 117 ><P
 118 ><B
 119 >Adding NLS support to a program</B
 120 ></P
 121 ><OL
 122 TYPE="1"
 123 ><LI
 124 ><P
 125 >     Insert this code into the start-up sequence of the program:
 126 </P><PRE
 127 CLASS="PROGRAMLISTING"
 128 >#ifdef ENABLE_NLS
 129 #include &lt;locale.h&gt;
 130 #endif
 131
 132 ...
 133
 134 #ifdef ENABLE_NLS
 135 setlocale(LC_ALL, "");
 136 bindtextdomain("<VAR
 137 CLASS="REPLACEABLE"
 138 >progname</VAR
 139 >", LOCALEDIR);
 140 textdomain("<VAR
 141 CLASS="REPLACEABLE"
 142 >progname</VAR
 143 >");
 144 #endif</PRE
 145 ><P>
 146      (The <VAR
 147 CLASS="REPLACEABLE"
 148 >progname</VAR
 149 > can actually be chosen
 150      freely.)
 151     </P
 152 ></LI
 153 ><LI
 154 ><P
 155 >     Wherever a message that is a candidate for translation is found,
 156      a call to <CODE
 157 CLASS="FUNCTION"
 158 >gettext()</CODE
 159 > needs to be inserted.  E.g.,
 160 </P><PRE
 161 CLASS="PROGRAMLISTING"
 162 >fprintf(stderr, "panic level %d\n", lvl);</PRE
 163 ><P>
 164      would be changed to
 165 </P><PRE
 166 CLASS="PROGRAMLISTING"
 167 >fprintf(stderr, gettext("panic level %d\n"), lvl);</PRE
 168 ><P>
 169      (<TT
 170 CLASS="SYMBOL"
 171 >gettext</TT
 172 > is defined as a no-op if no NLS is
 173      configured.)
 174     </P
 175 ><P
 176 >     This may tend to add a lot of clutter.  One common shortcut is to use
 177 </P><PRE
 178 CLASS="PROGRAMLISTING"
 179 >#define _(x) gettext(x)</PRE
 180 ><P>
 181      Another solution is feasible if the program does much of its
 182      communication through one or a few functions, such as
 183      <CODE
 184 CLASS="FUNCTION"
 185 >ereport()</CODE
 186 > in the backend.  Then you make this
 187      function call <CODE
 188 CLASS="FUNCTION"
 189 >gettext</CODE
 190 > internally on all
 191      input strings.
 192     </P
 193 ></LI
 194 ><LI
 195 ><P
 196 >     Add a file <TT
 197 CLASS="FILENAME"
 198 >nls.mk</TT
 199 > in the directory with the
 200      program sources.  This file will be read as a makefile.  The
 201      following variable assignments need to be made here:
 202
 203      <P
 204 ></P
 205 ></P><DIV
 206 CLASS="VARIABLELIST"
 207 ><DL
 208 ><DT
 209 ><VAR
 210 CLASS="VARNAME"
 211 >CATALOG_NAME</VAR
 212 ></DT
 213 ><DD
 214 ><P
 215 >         The program name, as provided in the
 216          <CODE
 217 CLASS="FUNCTION"
 218 >textdomain()</CODE
 219 > call.
 220         </P
 221 ></DD
 222 ><DT
 223 ><VAR
 224 CLASS="VARNAME"
 225 >AVAIL_LANGUAGES</VAR
 226 ></DT
 227 ><DD
 228 ><P
 229 >         List of provided translations -- empty in the beginning.
 230         </P
 231 ></DD
 232 ><DT
 233 ><VAR
 234 CLASS="VARNAME"
 235 >GETTEXT_FILES</VAR
 236 ></DT
 237 ><DD
 238 ><P
 239 >         List of files that contain translatable strings, i.e., those
 240          marked with <CODE
 241 CLASS="FUNCTION"
 242 >gettext</CODE
 243 > or an alternative
 244          solution.  Eventually, this will include nearly all source
 245          files of the program.  If this list gets too long you can
 246          make the first <SPAN
 247 CLASS="QUOTE"
 248 >"file"</SPAN
 249 > be a <TT
 250 CLASS="LITERAL"
 251 >+</TT
 252 >
 253          and the second word be a file that contains one file name per
 254          line.
 255         </P
 256 ></DD
 257 ><DT
 258 ><VAR
 259 CLASS="VARNAME"
 260 >GETTEXT_TRIGGERS</VAR
 261 ></DT
 262 ><DD
 263 ><P
 264 >         The tools that generate message catalogs for the translators
 265          to work on need to know what function calls contain
 266          translatable strings.  By default, only
 267          <CODE
 268 CLASS="FUNCTION"
 269 >gettext()</CODE
 270 > calls are known.  If you used
 271          <CODE
 272 CLASS="FUNCTION"
 273 >_</CODE
 274 > or other identifiers you need to list
 275          them here.  If the translatable string is not the first
 276          argument, the item needs to be of the form
 277          <TT
 278 CLASS="LITERAL"
 279 >func:2</TT
 280 > (for the second argument).
 281         </P
 282 ></DD
 283 ></DL
 284 ></DIV
 285 ><P>
 286     </P
 287 ></LI
 288 ></OL
 289 ></DIV
 290 ><P
 291 >   The build system will automatically take care of building and
 292    installing the message catalogs.
 293   </P
 294 ></DIV
 295 ><DIV
 296 CLASS="SECT2"
 297 ><H2
 298 CLASS="SECT2"
 299 ><A
 300 NAME="NLS-GUIDELINES"
 301 >46.2.2. Message-writing guidelines</A
 302 ></H2
 303 ><P
 304 >   Here are some guidelines for writing messages that are easily
 305    translatable.
 306
 307    <P
 308 ></P
 309 ></P><UL
 310 ><LI
 311 ><P
 312 >      Do not construct sentences at run-time, like
 313 </P><PRE
 314 CLASS="PROGRAMLISTING"
 315 >printf("Files were %s.\n", flag ? "copied" : "removed");</PRE
 316 ><P>
 317       The word order within the sentence may be different in other
 318       languages.  Also, even if you remember to call gettext() on each
 319       fragment, the fragments may not translate well separately.  It's
 320       better to duplicate a little code so that each message to be
 321       translated is a coherent whole.  Only numbers, file names, and
 322       such-like run-time variables should be inserted at runtime into
 323       a message text.
 324      </P
 325 ></LI
 326 ><LI
 327 ><P
 328 >      For similar reasons, this won't work:
 329 </P><PRE
 330 CLASS="PROGRAMLISTING"
 331 >printf("copied %d file%s", n, n!=1 ? "s" : "");</PRE
 332 ><P>
 333       because it assumes how the plural is formed.  If you figured you
 334       could solve it like this
 335 </P><PRE
 336 CLASS="PROGRAMLISTING"
 337 >if (n==1)
 338     printf("copied 1 file");
 339 else
 340     printf("copied %d files", n):</PRE
 341 ><P>
 342       then be disappointed.  Some languages have more than two forms,
 343       with some peculiar rules.  We may have a solution for this in
 344       the future, but for now the matter is best avoided altogether.
 345       You could write:
 346 </P><PRE
 347 CLASS="PROGRAMLISTING"
 348 >printf("number of copied files: %d", n);</PRE
 349 ><P>
 350      </P
 351 ></LI
 352 ><LI
 353 ><P
 354 >      If you want to communicate something to the translator, such as
 355       about how a message is intended to line up with other output,
 356       precede the occurrence of the string with a comment that starts
 357       with <TT
 358 CLASS="LITERAL"
 359 >translator</TT
 360 >, e.g.,
 361 </P><PRE
 362 CLASS="PROGRAMLISTING"
 363 >/* translator: This message is not what it seems to be. */</PRE
 364 ><P>
 365       These comments are copied to the message catalog files so that
 366       the translators can see them.
 367      </P
 368 ></LI
 369 ></UL
 370 ><P>
 371   </P
 372 ></DIV
 373 ></DIV
 374 ><DIV
 375 CLASS="NAVFOOTER"
 376 ><HR
 377 ALIGN="LEFT"
 378 WIDTH="100%"><TABLE
 379 SUMMARY="Footer navigation table"
 380 WIDTH="100%"
 381 BORDER="0"
 382 CELLPADDING="0"
 383 CELLSPACING="0"
 384 ><TR
 385 ><TD
 386 WIDTH="33%"
 387 ALIGN="left"
 388 VALIGN="top"
 389 ><A
 390 HREF="nls.html"
 391 ACCESSKEY="P"
 392 >Prev</A
 393 ></TD
 394 ><TD
 395 WIDTH="34%"
 396 ALIGN="center"
 397 VALIGN="top"
 398 ><A
 399 HREF="index.html"
 400 ACCESSKEY="H"
 401 >Home</A
 402 ></TD
 403 ><TD
 404 WIDTH="33%"
 405 ALIGN="right"
 406 VALIGN="top"
 407 ><A
 408 HREF="plhandler.html"
 409 ACCESSKEY="N"
 410 >Next</A
 411 ></TD
 412 ></TR
 413 ><TR
 414 ><TD
 415 WIDTH="33%"
 416 ALIGN="left"
 417 VALIGN="top"
 418 >Native Language Support</TD
 419 ><TD
 420 WIDTH="34%"
 421 ALIGN="center"
 422 VALIGN="top"
 423 ><A
 424 HREF="nls.html"
 425 ACCESSKEY="U"
 426 >Up</A
 427 ></TD
 428 ><TD
 429 WIDTH="33%"
 430 ALIGN="right"
 431 VALIGN="top"
 432 >Writing A Procedural Language Handler</TD
 433 ></TR
 434 ></TABLE
 435 ></DIV
 436 ></BODY
 437 ></HTML
 438 >