ok
Direktori : /opt/alt/postgresql11/usr/share/doc/alt-postgresql11-9.2.24/html/ |
Current File : //opt/alt/postgresql11/usr/share/doc/alt-postgresql11-9.2.24/html/nls-programmer.html |
<!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.2.24 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="2017-11-06T22:43:11"></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.2.24 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 48. 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" >48.2. For the Programmer</A ></H1 ><DIV CLASS="SECT2" ><H2 CLASS="SECT2" ><A NAME="NLS-MECHANICS" >48.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 <locale.h> #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 — 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" >48.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 >